Skip to content
ServiceNowPublic

About

Library for generating JSDocs annotations, originally written for Script Includes Index. See paper DeepCodeSeek: Real-Time API Retrieval for Context-Aware Code Generation

Topics

Resources

Stars

3 stars

Watchers

0 watching

Forks

Latest commit

 

History

28 Commits

Folders and files

Repository files navigation

Snowdoc – ServiceNow JSDoc generator

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).


Installation

Clone the repository and install dependencies using Poetry:

git clone https://github.com/ServiceNow/snowdoc
cd snowdoc
poetry install

Make sure you have either

  • AWS credentials + Bedrock access (for Claude 3 Sonnet) or
  • GEMINI_KEY in your environment for Google Gemini

stored in a .env file or exported as environment variables.


Configuration

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=...

Command-line usage

Single File Processing

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).

Batch Processing

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).

Examples

Generate a signature scaffold only:

poetry run snowdoc test.js -o test_jsdoc_signature.js

In-place documentation:

poetry run snowdoc -i test.js

Create a new annotated copy while keeping the original code intact:

poetry run snowdoc test.js -o annotated.js --inject-docs

Create a new annotated copy with ESLint validation:

poetry run snowdoc test.js -o annotated.js --inject-docs --eslint-check

In-place documentation with ESLint validation:

poetry run snowdoc -i test.js --eslint-check

Process a batch of files from a CSV:

poetry run snowdoc --batch-file scripts.csv --code-column script_code --output-column jsdoc_result

Process 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-check

Verification

Manual Verification

To 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.js

Automated Verification

You can use the built-in ESLint check feature for both single files and batch processing:

  1. Make sure you have ESLint and the JSDoc plugin installed (as shown above)
  2. Use the --eslint-check flag along with --inject-docs or --in-place for single files
  3. Use the --eslint-check flag along with --inject-docs when 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

About

Library for generating JSDocs annotations, originally written for Script Includes Index. See paper DeepCodeSeek: Real-Time API Retrieval for Context-Aware Code Generation

Topics

Resources

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages