tessl/npm-documentation

A comprehensive JavaScript documentation generator that transforms JSDoc-annotated source code into human-readable documentation in multiple formats

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Documentation Linting

Name: tessl/npm-documentation
Author: tessl

Validation system for JSDoc syntax and structure that checks for common mistakes, missing documentation, and style inconsistencies. Provides detailed error reporting to help maintain high-quality documentation standards.

Capabilities

Lint Function

Validates JSDoc syntax and documentation structure, returning human-readable lint output for identified issues.

/**
 * Lint files for non-standard or incorrect documentation information
 * @param indexes - Files to process (string or array of strings)
 * @param args - Configuration options for linting
 * @returns Promise that resolves to lint output string (empty if no issues)
 */
function lint(
  indexes: string[] | string,
  args: LintOptions
): Promise<string>;

interface LintOptions {
  /** String regex/glob pattern for external modules to include */
  external?: string[];
  /** Whether to avoid dependency parsing in JavaScript code */
  shallow?: boolean;
  /** Regular expression to infer private elements from naming */
  inferPrivate?: string;
  /** Additional file extensions to treat as JavaScript */
  extension?: string | string[];
  /** Configuration file path */
  config?: string;
  /** Parse additional file extensions */
  parseExtension?: string[];
}

Usage Examples:

import { lint } from "documentation";

// Basic linting
const lintOutput = await lint(['src/util.js']);
if (lintOutput) {
  console.log(lintOutput);
  process.exit(1);
} else {
  console.log('No lint issues found');
  process.exit(0);
}

// Lint with configuration
const lintOutput = await lint(['src/**/*.js'], {
  inferPrivate: '^_',
  external: ['lodash'],
  extension: ['ts', 'tsx']
});

// Shallow linting (no dependency resolution)
const lintOutput = await lint(['lib/index.js'], {
  shallow: true
});

Validation Rules

The linting system checks for various documentation quality issues:

Missing Documentation

Functions without JSDoc comments
Parameters without descriptions
Return values without documentation
Classes without descriptions

Syntax Errors

Malformed JSDoc tags
Invalid type expressions
Missing required tag elements
Inconsistent tag usage

Style Issues

Inconsistent parameter naming
Missing access level declarations
Incomplete type information
Orphaned documentation blocks

Type System Issues

Undefined type references
Inconsistent type declarations
Missing generic type parameters
Invalid type expressions

Lint Output Format

The lint function returns a formatted string containing all identified issues:

src/util.js:15: Missing JSDoc comment for function 'processData'
src/util.js:23: Parameter 'options' is missing description
src/util.js:35: Return type is not documented
src/models/user.js:8: @param tag is missing type information
src/models/user.js:42: Unknown type 'UserConfig' referenced

Each line includes:

File path: Location of the issue
Line number: Specific line where issue occurs
Issue description: Clear explanation of the problem

Configuration Options

Dependency Processing

Control how the linter processes file dependencies:

// Deep dependency analysis (default)
const lintOutput = await lint(['index.js'], {
  shallow: false
});

// Only lint specified files
const lintOutput = await lint(['index.js'], {
  shallow: true
});

Private Member Inference

Configure automatic detection of private members:

const lintOutput = await lint(['src/'], {
  // Methods starting with _ are treated as private
  inferPrivate: '^_'
});

File Extension Support

Specify additional file extensions to process:

const lintOutput = await lint(['src/'], {
  extension: ['ts', 'tsx', 'vue'],
  parseExtension: ['ts', 'tsx']
});

External Module Handling

Configure which external modules to include in linting:

const lintOutput = await lint(['src/'], {
  external: ['lodash.*', 'express', 'react']
});

Exit Codes

When used in CI/CD pipelines or scripts, check the lint output to determine success:

const lintOutput = await lint(['src/']);
if (lintOutput) {
  // Issues found - documentation needs improvement
  console.error('Documentation lint issues:');
  console.error(lintOutput);
  process.exit(1);
} else {
  // No issues found - documentation is clean
  console.log('Documentation passes all lint checks');
  process.exit(0);
}

Integration with Build Systems

The linting function integrates well with various build tools and CI systems:

npm scripts:

{
  "scripts": {
    "lint:docs": "documentation lint src/",
    "test": "npm run lint:docs && jest"
  }
}

GitHub Actions:

- name: Lint documentation
  run: npx documentation lint src/

Common Lint Issues and Solutions

Missing JSDoc Comments

// Problem: No JSDoc comment
function calculateTotal(items) {
  return items.reduce((sum, item) => sum + item.price, 0);
}

// Solution: Add JSDoc comment
/**
 * Calculate the total price of all items
 * @param {Array<Object>} items - Array of items with price property
 * @returns {number} Total price of all items
 */
function calculateTotal(items) {
  return items.reduce((sum, item) => sum + item.price, 0);
}

Missing Parameter Descriptions

// Problem: Parameter without description
/**
 * Process user data
 * @param {Object} data
 * @param {Object} options
 */
function processUser(data, options) { }

// Solution: Add parameter descriptions
/**
 * Process user data
 * @param {Object} data - User data to process
 * @param {Object} options - Processing configuration options
 */
function processUser(data, options) { }

Install with Tessl CLI