Snowdoc turns any ServiceNow-style Script Include (or plain JavaScript file) into a well-structured and descriptive JSDoc signature using an LLM (Anthropic Claude or Google Gemini).
Clone the repository and install dependencies using Poetry:
git clone https://github.com/ServiceNow/snowdoc
cd snowdoc
poetry installMake sure you have either
- AWS credentials + Bedrock access (for Claude 3 Sonnet) or
GEMINI_KEYin your environment for Google Gemini
stored in a .env file or exported as environment variables.
Snowdoc needs credentials for one of the supported LLM back-ends.
Create a .env file or export the variables in your shell.
# AWS Bedrock / Claude 3 Sonnet
CLAUDE_AWS_ACCESS_KEY_ID=...
CLAUDE_AWS_SECRET_ACCESS_KEY=...
CLAUDE_AWS_DEFAULT_REGION=...
# Google Gemini
GEMINI_KEY=...poetry run snowdoc [OPTIONS] FILE| Option | Description |
|---|---|
-i, --in-place |
Overwrite FILE by merging JSDoc blocks into the code. |
-o, --output PATH |
Write result to PATH. If omitted the scaffold is printed to stdout. |
--inject-docs |
When used together with --output, merges JSDoc into the code but saves the merged version to PATH (leaving the original file untouched). |
--eslint-check |
Run ESLint check on the file (requires --inject-docs or --in-place). |
--provider {claude,gemini} |
Choose the LLM backend (default claude). |
Process multiple rows of JavaScript code at once using a CSV or Excel file:
poetry run snowdoc --batch-file FILE.csv --code-column COLUMN1 --output-column COLUMN2 [OPTIONS]| Option | Description |
|---|---|
--batch-file PATH |
Path to a CSV or XLSX file containing code to process. |
--code-column NAME |
Column name in batch file containing JavaScript code content. |
--output-column NAME |
Column name in batch file to write generated JSDoc signatures. |
--output PATH |
Optional path to save the processed batch file (if not specified, updates the original file). |
--inject-docs |
Generate JSDoc blocks injected into the code rather than just signatures. |
--eslint-check |
Run ESLint check on each file in batch mode (requires --inject-docs). |
--provider {claude,gemini} |
Choose the LLM backend (default claude). |
Generate a signature scaffold only:
poetry run snowdoc test.js -o test_jsdoc_signature.jsIn-place documentation:
poetry run snowdoc -i test.jsCreate a new annotated copy while keeping the original code intact:
poetry run snowdoc test.js -o annotated.js --inject-docsCreate a new annotated copy with ESLint validation:
poetry run snowdoc test.js -o annotated.js --inject-docs --eslint-checkIn-place documentation with ESLint validation:
poetry run snowdoc -i test.js --eslint-checkProcess a batch of files from a CSV:
poetry run snowdoc --batch-file scripts.csv --code-column script_code --output-column jsdoc_resultProcess a batch of files and validate JSDoc with ESLint:
poetry run snowdoc --batch-file scripts.csv --code-column script_code --output-column jsdoc_result --inject-docs --eslint-checkTo verify a sample .JS file with generated JSDoc annotation in it, run eslint:
npm install --save-dev eslint eslint-plugin-jsdoc
npx eslint samples/annotated.jsYou can use the built-in ESLint check feature for both single files and batch processing:
- Make sure you have ESLint and the JSDoc plugin installed (as shown above)
- Use the
--eslint-checkflag along with--inject-docsor--in-placefor single files - Use the
--eslint-checkflag along with--inject-docswhen running batch processing
How ESLint results are presented:
- Single file mode: Results are displayed in the console only, keeping your output files clean
- Batch processing mode: Results are added to a separate "ESLint" column in the batch file