CLI Usage

npm install -g dox

npm install dox
# Then use with npx: npx dox [options]

# Basic usage - parse JavaScript and output JSON
dox < input.js > output.json

# Generate markdown API documentation
dox --api < input.js > README.md

# Debug mode for human-readable output
dox --debug < input.js

# Process multiple files (shell expansion)
cat src/*.js | dox > docs.json

Usage: dox [options]

Options:
  -h, --help                     Display usage information and examples
  -V, --version                  Display version number
  -r, --raw                      Output raw comments, leaving markdown intact
  -a, --api                      Output markdown readme documentation
  -s, --skipPrefixes [prefixes]  Skip comments prefixed with these prefixes (comma-separated)
  -d, --debug                    Output parsed comments for debugging (human-readable)
  -S, --skipSingleStar           Ignore /* ... */ comments, only process /** ... */

# Parse a single file
dox < mymodule.js > mymodule.json

# Parse and pretty-print JSON
dox < mymodule.js | jq . > formatted.json

# Example output structure:
[
  {
    "tags": [
      {
        "type": "param",
        "types": ["string"],
        "name": "text",
        "description": "Text to process"
      },
      {
        "type": "return", 
        "types": ["string"],
        "description": "Processed text"
      }
    ],
    "description": {
      "full": "<p>Process the given text</p>",
      "summary": "<p>Process the given text</p>",
      "body": ""
    },
    "isPrivate": false,
    "ignore": false,
    "code": "function processText(text) { return text.trim(); }",
    "ctx": {
      "type": "function",
      "name": "processText",
      "string": "processText()"
    }
  }
]

# Generate API documentation
dox --api < src/utils.js > docs/API.md

# Generate docs for entire project
find src -name "*.js" -exec cat {} \; | dox --api > README.md

# Example markdown output:
# API Documentation
# 
# - [processText()](#processtext)
# - [User.getName()](#usergetname)
# 
# ### processText(text:string)
# 
# Process the given text and return cleaned version.

# Human-readable debug output
dox --debug < myfile.js

# Example debug output (colored in terminal):
{
  tags: [
    {
      type: 'param',
      name: 'data',
      description: 'Input data to process',
      types: [ 'Object' ]
    }
  ],
  description: {
    full: '<p>Process input data</p>',
    summary: '<p>Process input data</p>',
    body: ''
  },
  ctx: {
    type: 'function',
    name: 'processData',
    string: 'processData()'
  }
}

# Skip markdown processing, preserve original text
dox --raw < myfile.js > raw.json

# Useful for custom markdown processing
dox --raw --api < myfile.js > raw_docs.md

# Skip linter comments
dox --skipPrefixes jshint,jslint,eslint < myfile.js > filtered.json

# Skip single-star comments (only process /** ... */)
dox --skipSingleStar < myfile.js > docs.json

{
  "scripts": {
    "docs": "find src -name '*.js' -exec cat {} \\; | dox --api > API.md",
    "docs:json": "find src -name '*.js' -exec cat {} \\; | dox > docs.json",
    "docs:debug": "dox --debug < src/main.js"
  }
}

docs: $(wildcard src/*.js)
	cat src/*.js | dox --api > README.md

docs-json: $(wildcard src/*.js)  
	cat src/*.js | dox > docs/api.json

.PHONY: docs docs-json

name: Generate Documentation
on: [push]
jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: '16'
      - run: npm install -g dox
      - run: find src -name "*.js" -exec cat {} \; | dox --api > API.md
      - run: git add API.md && git commit -m "Update docs" && git push

#!/bin/sh
# .git/hooks/pre-commit

# Generate fresh documentation
find src -name "*.js" -exec cat {} \; | dox --api > API.md

# Add updated docs to commit
git add API.md

# From file
dox < myfile.js

# From pipe
cat src/*.js | dox

# From command substitution
echo "/** Comment */ function test() {}" | dox

# From heredoc
dox << 'EOF'
/**
 * Example function
 * @param {string} name
 */
function greet(name) {
  return "Hello " + name;
}
EOF

# JSON (default)
dox < file.js
# Output: [{"tags": [], "description": {...}, ...}]

# Pretty JSON with debug
dox --debug < file.js  
# Output: Formatted, colored object inspection

# Markdown
dox --api < file.js
# Output: # API Documentation\n\n### function()\n\n...

# Raw JSON (no markdown processing)
dox --raw < file.js
# Output: [{"description": {"full": "Raw text", ...}, ...}]

# Success
echo "/** test */ function f() {}" | dox
echo $? # 0

# Invalid options
dox --invalid-option
echo $? # 1

# Help and version (success)
dox --help
echo $? # 0

# Generate docs with custom template
dox --api < src/api.js | \
  sed 's/^# API Documentation/# MyProject API/' > \
  docs/api.md

# Extract only function signatures
dox < src/utils.js | \
  jq -r '.[] | select(.ctx.type == "function") | .ctx.string'

# Count documented functions
dox < src/main.js | \
  jq '[.[] | select(.ctx.type == "function")] | length'

# Generate individual doc files
for file in src/*.js; do
  basename=$(basename "$file" .js)
  dox --api < "$file" > "docs/${basename}.md"
done

# Combine multiple files with headers
for file in src/*.js; do
  echo "# $(basename "$file")"
  dox --api < "$file" 
  echo ""  
done > combined-docs.md

#!/bin/bash
# scripts/generate-docs.sh

DOX_OPTIONS="--api --skipPrefixes jshint,eslint --skipSingleStar"
find src -name "*.js" -exec cat {} \; | dox $DOX_OPTIONS > API.md