tessl/npm-dox

JavaScript documentation generator that parses JSDoc-style comments and outputs structured JSON data

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

JSDoc Tags

Name: tessl/npm-dox
Author: tessl

Advanced JSDoc tag parsing with support for complex type annotations and all standard JSDoc tags.

Capabilities

Parse Tag

Parses individual JSDoc tag strings into structured objects with type information and metadata.

/**
 * Parse a JSDoc tag string into structured data
 * @param {string} str - Tag string to parse (e.g., "@param {string} name Description")
 * @returns {TagObject} Parsed tag object with type and metadata
 */
function parseTag(str);

Usage Examples:

const dox = require('dox');

// Parameter tag with type
const paramTag = dox.parseTag('@param {string|number} value The input value');
console.log(paramTag);
// Output:
// {
//   type: 'param',
//   name: 'value',
//   description: 'The input value',
//   types: ['string', 'number'],
//   typesDescription: '<code>string</code>|<code>number</code>',
//   optional: false,
//   nullable: false,
//   nonNullable: false,
//   variable: false,
//   string: '{string|number} value The input value'
// }

// Return tag
const returnTag = dox.parseTag('@return {Promise<User[]>} Array of user objects');
console.log(returnTag.types); // ['Promise<User[]>']

// Complex object type
const complexTag = dox.parseTag('@param {{name: string, age: number}} user User object');
console.log(complexTag.types);
// Output: [{ name: ['string'], age: ['number'] }]

Parse Tag Types

Parses JSDoc type strings with support for complex type annotations including union types, object types, generics, and nullable/optional indicators.

/**
 * Parse JSDoc type string into structured types array
 * @param {string} str - Type string in JSDoc format (e.g., "{string|number}")
 * @param {Object} [tag] - Tag object to populate with parsed type data
 * @returns {Array} Array of parsed type structures
 */
function parseTagTypes(str, tag);

Usage Examples:

const dox = require('dox');

// Union types
const unionTypes = dox.parseTagTypes('{string|number|null}');
console.log(unionTypes); // ['string', 'number', 'null']

// Optional parameter
const optionalTypes = dox.parseTagTypes('{string=}');
console.log(optionalTypes); // ['string']

// Nullable type
const nullableTypes = dox.parseTagTypes('{?string}');
console.log(nullableTypes); // ['string']

// Complex object type
const objectTypes = dox.parseTagTypes('{Object<string, number>}');
console.log(objectTypes); // ['Object<string, number>']

// Record type
const recordTypes = dox.parseTagTypes('{{name: string, age: number}}');
console.log(recordTypes);
// Output: [{ name: ['string'], age: ['number'] }]

// Populate tag object with metadata
const tag = {};
dox.parseTagTypes('{string=}', tag);
console.log(tag.optional); // true
console.log(tag.typesDescription); // '<code>string</code>|<code>undefined</code>'

Extract Tag Parts

Splits JSDoc tag strings into components while respecting type brackets and braces.

/**
 * Split tag string into parts while respecting braces in type annotations
 * @param {string} str - Tag string to split
 * @returns {string[]} Array of tag parts
 */
function extractTagParts(str);

Usage Examples:

const dox = require('dox');

// Simple tag
const simpleParts = dox.extractTagParts('@param {string} name Description text');
console.log(simpleParts);
// Output: ['@param', '{string}', 'name', 'Description', 'text']

// Complex type with spaces
const complexParts = dox.extractTagParts('@param {string | number} value The input');
console.log(complexParts);
// Output: ['@param', '{string | number}', 'value', 'The', 'input']

// Object type
const objectParts = dox.extractTagParts('@param {{name: string, age: number}} user');
console.log(objectParts);
// Output: ['@param', '{{name: string, age: number}}', 'user']

Parameter Optional Detection

Determines if a parameter is optional based on JSDoc syntax conventions.

/**
 * Determine if a parameter is optional based on JSDoc syntax
 * @param {TagObject} tag - Tag object to check for optional indicators
 * @returns {boolean} True if parameter is optional
 */
function parseParamOptional(tag);

Usage Examples:

const dox = require('dox');

// Square bracket syntax: [param]
const bracketTag = dox.parseTag('@param {string} [name] Optional name');
console.log(dox.parseParamOptional(bracketTag)); // true

// Google Closure syntax: {Type=}
const googleTag = dox.parseTag('@param {string=} name Optional name');
console.log(dox.parseParamOptional(googleTag)); // true

// TypeScript syntax: {Type?}
const tsTag = dox.parseTag('@param {string?} name Optional name');
console.log(dox.parseParamOptional(tsTag)); // true

// Required parameter
const requiredTag = dox.parseTag('@param {string} name Required name');
console.log(dox.parseParamOptional(requiredTag)); // false

Supported JSDoc Tags

Dox supports all standard JSDoc tags with intelligent parsing:

Core Tags

@param - Function/method parameters with type annotations
@return/@returns - Return value types and descriptions
@throws - Exception types that may be thrown
@example - Usage examples (preserved as code blocks)

Documentation Tags

@description - Explicit description content
@summary - Brief summary text
@see - References to related documentation or URLs
@api - API visibility (public, private, protected)

Structure Tags

@class - Class declarations
@constructor - Constructor functions
@namespace - Namespace definitions
@memberOf - Member ownership
@lends - Object literal member assignment

Type Tags

@type - Variable type annotation
@typedef - Custom type definitions
@enum - Enumeration types
@template - Generic type parameters

Inheritance Tags

@extends/@augments - Class inheritance
@implements - Interface implementation
@borrows - Method borrowing

Metadata Tags

@version - Version information
@since - Version introduced
@deprecated - Deprecation notices
@author - Author information

Data Structures

Tag Object

interface TagObject {
  /** Tag type (param, return, see, etc.) */
  type: string;
  /** Parameter or property name (for @param, @property tags) */
  name?: string;
  /** Tag description text */
  description: string;
  /** Array of parsed type structures */
  types: Array<string | Object>;
  /** Formatted HTML representation of types */
  typesDescription: string;
  /** True if parameter is optional */
  optional: boolean;
  /** True if type can be null */
  nullable: boolean;
  /** True if type explicitly cannot be null */
  nonNullable: boolean;
  /** True if parameter accepts variable arguments (...args) */
  variable: boolean;
  /** API visibility level */
  visibility?: 'public' | 'private' | 'protected';
  /** Original tag string */
  string: string;
  /** Additional tag-specific properties */
  [key: string]: any;
}

Type Parsing Features

Dox supports the full range of JSDoc type annotations:

// Basic types
{string}
{number}
{boolean}
{Object}
{Array}

// Union types
{string|number}
{string|number|null}

// Nullable and non-nullable
{?string}    // nullable
{!string}    // non-nullable

// Optional parameters
{string=}    // Google Closure syntax
[param]      // JSDoc bracket syntax
{string?}    // TypeScript-style syntax

// Generic types
{Array<string>}
{Promise<User>}
{Object<string, number>}

// Record types (object literals)
{{name: string, age: number}}
{{prop1: string, prop2: {nested: boolean}}}

// Variable arguments
{...string}   // rest parameters
{string...}   // variadic

// Complex combinations
{Array<{id: number, name: string}>}
{Promise<Array<User>>}
{(string|number)[]|null}