Revise public documentation for codegen (#906)

Author: jeffcharles

crates/codegen/CHANGELOG.md

@@ -6,6 +6,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic
 Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [1.0.0] - 2025-2-15
+## [1.0.0] - 2025-03-07
 
 Initial release

crates/codegen/src/js.rs

@@ -26,21 +26,21 @@ use swc_core::{
 
 use crate::plugin::Plugin;
 
-/// A structure representing valid JS code.
+/// JS source code.
 #[derive(Clone, Debug)]
 pub struct JS {
     source_code: Rc<String>,
 }
 
 impl JS {
-    /// Generate a valid JS instance from a string containing JS.
+    /// Create [`JS`] from a string containing JS source code.
     pub fn from_string(source_code: String) -> JS {
         JS {
             source_code: Rc::new(source_code),
         }
     }
 
-    /// Generate a valid JS instance from a file containing JS.
+    /// Create [`JS`] from a file containing JS.
     pub fn from_file(path: &Path) -> Result<JS> {
         let mut input_file = File::open(path)
             .with_context(|| format!("Failed to open input file {}", path.display()))?;
@@ -49,7 +49,7 @@ impl JS {
         Ok(Self::from_string(String::from_utf8(contents)?))
     }
 
-    /// Get JS source code as bytes.
+    /// Get source code as bytes.
     pub fn as_bytes(&self) -> &[u8] {
         self.source_code.as_bytes()
     }

crates/codegen/src/lib.rs

@@ -1,7 +1,7 @@
 //! WebAssembly Code Generation for JavaScript
 //!
-//! This module provides all the functionality to emit Wasm modules for
-//! a particular JavaScript program.
+//! This module provides functionality to emit Wasm modules which will run
+//! JavaScript source code with the QuickJS interpreter.
 //!
 //! Javy supports two main code generation paths:
 //!
@@ -41,32 +41,34 @@
 //! use javy_codegen::{Generator, LinkingKind, Plugin, JS};
 //!
 //! fn main() -> Result<(), Box<dyn std::error::Error>> {
-//!  // Load your target Javascript.
-//!  let js = JS::from_file(Path::new("example.js"))?;
+//!     // Load your target Javascript.
+//!     let js = JS::from_file(Path::new("example.js"))?;
 //!
-//!  // Load existing pre-initialized Javy plugin.
-//!  let plugin = Plugin::new_from_path(Path::new("example-plugin.wasm"))?;
+//!     // Load existing pre-initialized Javy plugin.
+//!     let plugin = Plugin::new_from_path(Path::new("example-plugin.wasm"))?;
 //!
-//!  // Configure code generator.
-//!  let mut generator = Generator::new(plugin);
-//!  generator.linking(LinkingKind::Static);
+//!     // Configure code generator.
+//!     let mut generator = Generator::new(plugin);
+//!     generator.linking(LinkingKind::Static);
 //!
-//!  // Generate your WASM module.
-//!  let wasm = generator.generate(&js);
+//!     // Generate your Wasm module.
+//!     let wasm = generator.generate(&js);
 //!
-//!  Ok(())
+//!     Ok(())
 //! }
 //! ```
 //!
 //! ## Core concepts
 //! * [`Generator`] - The main entry point for generating Wasm modules.
-//! * [`Plugin`] - Represents a pre-initialized Javy plugin.
-//! * [`JS`] - Represents a JavaScript bytecode.
+//! * [`Plugin`] - An initialized Javy plugin.
+//! * [`JS`] - JavaScript source code.
 //!
 //! ## Features
 //!
-//! * `plugin_internal` - Enables additional code generation options for internal use.
-//! >  Please note that this flag enables an unstable feature. The unstable API's exposed by this future may break in the future without notice.
+//! * `plugin_internal` - Enables additional code generation options for
+//!   internal use. Please note that this flag enables an unstable feature. The
+//!   unstable API's exposed by this future may break in the future without
+//!   notice.
 
 use std::{fs, rc::Rc, sync::OnceLock};
 
@@ -147,8 +149,7 @@ impl BytecodeMetadata {
     }
 }
 
-/// Generator used to produce valid Wasm
-/// binaries from JS.
+/// Generator used to produce Wasm binaries from JS source code.
 #[derive(Default, Clone)]
 pub struct Generator {
     /// Plugin to use.
@@ -558,7 +559,7 @@ impl Generator {
     //    (data (;0;) "\02\05\18function.mjs\06foo\0econsole\06log\06bar\0f\bc\03\00\01\00\00\be\03\00\00\0e\00\06\01\a0\01\00\00\00\03\01\01\1a\00\be\03\00\01\08\ea\05\c0\00\e1)8\e0\00\00\00B\e1\00\00\00\04\e2\00\00\00$\01\00)\bc\03\01\04\01\00\07\0a\0eC\06\01\be\03\00\00\00\03\00\00\13\008\e0\00\00\00B\e1\00\00\00\04\df\00\00\00$\01\00)\bc\03\01\02\03]")
     //    (data (;1;) "foo")
     //  )
-    /// Generate a valid WASM binary from JS.
+    /// Generate a Wasm module which will run the provided JS source code.
     pub fn generate(&mut self, js: &js::JS) -> Result<Vec<u8>> {
         if self.wit_opts.defined() {
             self.function_exports = exports::process_exports(

crates/codegen/src/plugin.rs

@@ -3,7 +3,7 @@ use std::{borrow::Cow, fs, path::Path, str};
 
 use super::bytecode;
 
-/// Represents the kind of a plugin.
+/// The kind of a plugin.
 // This is an internal detail of this module.
 #[derive(Default, PartialEq, Copy, Clone)]
 #[allow(dead_code)] // Suppresses warnings for feature-gated variants
@@ -16,7 +16,6 @@ pub(crate) enum PluginKind {
 
 impl PluginKind {
     /// Determine the import namespace of a provided plugin.
-    // This is an internal detail of this module.
     pub(crate) fn import_namespace(self, plugin: &Plugin) -> Result<String> {
         match self {
             PluginKind::V2 => Ok("javy_quickjs_provider_v2".to_string()),
@@ -41,30 +40,30 @@ impl PluginKind {
     }
 }
 
-/// Represents any valid Javy plugin.
+/// A Javy plugin.
 #[derive(Clone, Debug, Default)]
 pub struct Plugin {
     bytes: Cow<'static, [u8]>,
 }
 
 impl Plugin {
-    /// Constructs a new instance of Plugin.
+    /// Constructs a new [`Plugin`].
     pub fn new(bytes: Cow<'static, [u8]>) -> Self {
         Plugin { bytes }
     }
 
-    /// Constructs a new instance of Plugin from a given path.
+    /// Constructs a new [`Plugin`] from a given path.
     pub fn new_from_path<P: AsRef<Path>>(path: P) -> Result<Self> {
         let bytes = fs::read(path)?;
         Ok(Self::new(bytes.into()))
     }
 
-    /// Returns the Plugin as a byte slice.
+    /// Returns the [`Plugin`] as bytes
     pub fn as_bytes(&self) -> &[u8] {
         &self.bytes
     }
 
-    /// Generate valid QuickJS bytecode from Javascript using a Plugin.
+    /// Generate valid QuickJS bytecode from Javascript source code.
     pub(crate) fn compile_source(&self, js_source_code: &[u8]) -> Result<Vec<u8>> {
         bytecode::compile_source(self.as_bytes(), js_source_code)
     }

docs/docs-contributing-architecture.md

@@ -6,15 +6,16 @@ This document is intended to provide an overview of the architecture of `javy`.
 
 ```mermaid
 flowchart TD
-  javy-cli --> wasm
+  javy-cli --> javy-codegen --> wasm
   subgraph wasm[plugin.wasm]
   javy-plugin --> javy-plugin-api
   javy-plugin-api --> javy
   javy --> rquickjs
   end
 ```
 
-We anticipate most changes will be to the `javy-cli` and `javy` crates.
+We anticipate most changes will be to the `javy-cli`, `javy-codegen`, and
+`javy` crates.
 
 ### `javy`
 
@@ -102,9 +103,9 @@ by a Cargo feature on a case-by-case basis.
 
 ### `javy-cli`
 
-The CLI for compiling JS to Wasm. This isn't intended to be a CLI that
-accommodates all uses for all users but rather to provide a useful base of
-functionality. 
+The CLI that drives the `javy-codegen` crate to compile JS to Wasm. This
+isn't intended to be a CLI that accommodates all uses for all users but
+rather to provide a useful base of functionality. 
 
 #### When to add a `cargo` feature
 
@@ -119,6 +120,10 @@ You should gate your feature with a cargo feature if your feature/change:
   run when the `javy-plugin` crate is built with a non-default configuration (that
   is, with different cargo features enabled).
 
+### `javy-codegen`
+
+A Rust crate for compiling JS to Wasm.
+
 ### `javy-plugin`
 
 Gets compiled to `plugin.wasm` for use by the CLI and in environments for

docs/docs-contributing-testing-locally.md

@@ -15,5 +15,5 @@ cargo +stable install cargo-hack --locked
 
 3. Run tests, eg:
 ```
-CARGO_TARGET_WASM32_WASIP1_RUNNER="wasmtime --dir=." cargo hack test --target=wasm32-wasip1 --workspace --exclude=javy-cli --each-feature -- --nocapture
+make tests
 ```

docs/docs-using-runtime-requirements.md

@@ -1,5 +1,5 @@
 ## Runtime requirements
 
-When running the official Javy binary on Linux, `glibc` 2.31 or greater must be
+When running the official Javy binary on Linux, `glibc` 2.35 or greater must be
 available. You may need to update the version of your operating system if you
 are using an older version of `glibc`.