chore: document noir_wasm

compiler/wasm/README.md

@@ -1,9 +1,32 @@
 # Noir Lang WASM JavaScript Package
 
-This JavaScript package enables users to compile a Noir program, i.e. generating its artifacts.
+This JavaScript package enables users to compile a Noir program, i.e. generating its artifacts, both in Node.JS environments and the browser.
 
 The package also handles dependency management like how Nargo (Noir's CLI tool) operates, but the package is used just for compilation, not proving, verifying and simulating functions.
 
+## Usage
+
+```typescript
+// Node.js
+
+import { compile, createFileManager } from '@noir-lang/noir_wasm';
+
+const fm = createFileManager(myProjectPath);
+const myCompiledCode = await compile(fm);
+```
+
+```typescript
+// Browser
+
+import { compile, createFileManager } from '@noir-lang/noir_wasm';
+
+const fm = createFileManager('/');
+for (const path of files) {
+  await fm.writeFile(path, await getFileAsStream(path));
+}
+const myCompiledCode = await compile(fm);
+```
+
 ## Building from source
 
 Outside of the [noir repo](https://github.com/noir-lang/noir), this package can be built using the command below:

compiler/wasm/src/index.cts

@@ -5,6 +5,36 @@ import { LogData, LogFn } from './utils';
 import { CompilationResult } from './types/noir_artifact';
 import { inflateDebugSymbols } from './noir/debug';
 
+/**
+ * Compiles a Noir project
+ *
+ * @param fileManager - The file manager to use
+ * @param projectPath - The path to the project inside the file manager. Defaults to the root of the file manager
+ * @param logFn - A logging function. If not provided, console.log will be used
+ * @param debugLogFn - A debug logging function. If not provided, logFn will be used
+ *
+ * @example
+ * ```typescript
+ * // Node.js
+ *
+ * import { compile, createFileManager } from '@noir-lang/noir_wasm';
+ *
+ * const fm = createFileManager(myProjectPath);
+ * const myCompiledCode = await compile(fm);
+ * ```
+ *
+ * ```typescript
+ * // Browser
+ *
+ * import { compile, createFileManager } from '@noir-lang/noir_wasm';
+ *
+ * const fm = createFileManager('/');
+ * for (const path of files) {
+ *   await fm.writeFile(path, await getFileAsStream(path));
+ * }
+ * const myCompiledCode = await compile(fm);
+ * ```
+ */
 async function compile(
   fileManager: FileManager,
   projectPath?: string,

compiler/wasm/src/index.mts

@@ -5,6 +5,36 @@ import { LogData, LogFn } from './utils';
 import { CompilationResult } from './types/noir_artifact';
 import { inflateDebugSymbols } from './noir/debug';
 
+/**
+ * Compiles a Noir project
+ *
+ * @param fileManager - The file manager to use
+ * @param projectPath - The path to the project inside the file manager. Defaults to the root of the file manager
+ * @param logFn - A logging function. If not provided, console.log will be used
+ * @param debugLogFn - A debug logging function. If not provided, logFn will be used
+ *
+ * @example
+ * ```typescript
+ * // Node.js
+ *
+ * import { compile, createFileManager } from '@noir-lang/noir_wasm';
+ *
+ * const fm = createFileManager(myProjectPath);
+ * const myCompiledCode = await compile(fm);
+ * ```
+ *
+ * ```typescript
+ * // Browser
+ *
+ * import { compile, createFileManager } from '@noir-lang/noir_wasm';
+ *
+ * const fm = createFileManager('/');
+ * for (const path of files) {
+ *   await fm.writeFile(path, await getFileAsStream(path));
+ * }
+ * const myCompiledCode = await compile(fm);
+ * ```
+ */
 async function compile(
   fileManager: FileManager,
   projectPath?: string,

compiler/wasm/src/noir/debug.ts

@@ -1,6 +1,9 @@
 import { inflate } from 'pako';
 
-/** Decompresses and decodes the debug symbols */
+/**
+ * Decompresses and decodes the debug symbols
+ * @param debugSymbols - The base64 encoded debug symbols
+ */
 export function inflateDebugSymbols(debugSymbols: string) {
   return JSON.parse(inflate(Buffer.from(debugSymbols, 'base64'), { to: 'string', raw: true }));
 }

compiler/wasm/src/noir/file-manager/nodejs-file-manager.ts

@@ -18,8 +18,9 @@ export async function readdirRecursive(dir: string): Promise<string[]> {
 }
 
 /**
- * Creates a new FileManager instance based on nodejs fs
- * @param dataDir - where to store files
+ * Creates a new FileManager instance based on fs in node and memfs in the browser (via webpack alias)
+ *
+ * @param dataDir - root of the file system
  */
 export function createNodejsFileManager(dataDir: string): FileManager {
   return new FileManager(

docs/docusaurus.config.ts

@@ -26,7 +26,7 @@ export default {
       '@docusaurus/preset-classic',
       {
         docs: {
-          path: "processed-docs",
+          path: 'processed-docs',
           sidebarPath: './sidebars.js',
           routeBasePath: '/docs',
           remarkPlugins: [math],
@@ -210,6 +210,37 @@ export default {
         membersWithOwnFile: ['Interface', 'Class', 'TypeAlias'],
       },
     ],
+    [
+      'docusaurus-plugin-typedoc',
+      {
+        id: 'noir_wasm',
+        entryPoints: ['../compiler/wasm/src/index.cts'],
+        tsconfig: '../compiler/wasm/tsconfig.json',
+        entryPointStrategy: 'resolve',
+        out: 'processed-docs/reference/NoirJS/noir_wasm',
+        plugin: ['typedoc-plugin-markdown'],
+        name: 'noir_wasm',
+        disableSources: true,
+        excludePrivate: true,
+        skipErrorChecking: true,
+        sidebar: {
+          filteredIds: ['reference/noir_wasm/index'],
+        },
+        readme: 'none',
+        hidePageHeader: true,
+        hideBreadcrumbs: true,
+        hideInPageTOC: true,
+        useCodeBlocks: true,
+        typeDeclarationFormat: 'table',
+        propertiesFormat: 'table',
+        parametersFormat: 'table',
+        enumMembersFormat: 'table',
+        indexFormat: 'table',
+        outputFileStrategy: 'members',
+        memberPageTitle: '{name}',
+        membersWithOwnFile: ['Function', 'TypeAlias'],
+      },
+    ],
   ],
   markdown: {
     format: 'detect',