Comment Parsing

/**
 * Parse comments in the given string of JavaScript code
 * @param {string} js - JavaScript source code to parse
 * @param {Object} [options] - Parsing options
 * @param {boolean} [options.raw] - Skip markdown processing, leave markdown intact
 * @param {boolean} [options.skipSingleStar] - Ignore /* ... */ style comments
 * @param {string[]} [options.skipPrefixes] - Array of comment prefixes to skip
 * @returns {CommentObject[]} Array of parsed comment objects
 */
function parseComments(js, options);

const dox = require('dox');

// Basic usage
const source = `
/**
 * Escape HTML characters in a string
 * @param {string} html - String to escape
 * @return {string} Escaped HTML string
 * @api public
 */
function escape(html) {
  return String(html)
    .replace(/&/g, '&')
    .replace(/</g, '&lt;')
    .replace(/>/g, '&gt;');
}
`;

const comments = dox.parseComments(source);
console.log(comments[0].description.full);
// Output: '<p>Escape HTML characters in a string</p>'

// Raw mode - skip markdown processing
const rawComments = dox.parseComments(source, { raw: true });
console.log(rawComments[0].description.full);
// Output: 'Escape HTML characters in a string'

// Skip linter comments
const sourceWithLinter = `
/* jshint strict: false */
/**
 * My function documentation
 */
function myFunc() {}
`;

const filtered = dox.parseComments(sourceWithLinter, {
  skipPrefixes: ['jshint', 'jslint']
});
// jshint comment will be filtered out

/**
 * Parse a single comment string into structured data
 * @param {string} str - Comment string to parse (without /** */ wrapper)
 * @param {Object} [options] - Parsing options
 * @param {boolean} [options.raw] - Skip markdown processing
 * @returns {CommentObject} Parsed comment object
 */
function parseComment(str, options);

const dox = require('dox');

// Parse individual comment
const commentStr = `
 * Calculate the sum of two numbers
 * 
 * This function adds two numeric values together
 * and returns the result.
 * 
 * @param {number} a - First number
 * @param {number} b - Second number
 * @return {number} Sum of a and b
 * @example
 *     add(2, 3)
 *     // => 5
 * @api public
`;

const comment = dox.parseComment(commentStr);
console.log(comment.description.summary);
// Output: '<p>Calculate the sum of two numbers</p>'
console.log(comment.tags.length); // 4 tags: param, param, return, example, api

/**
 * Remove excess indentation from code string
 * @param {string} str - Code string with potentially excessive indentation
 * @returns {string} String with normalized indentation
 */
function trimIndentation(str);

const dox = require('dox');

const indentedCode = `
    function test() {
        return true;
    }
`;

const normalized = dox.trimIndentation(indentedCode);
console.log(normalized);
// Output:
// function test() {
//     return true;
// }

interface CommentObject {
  /** Array of parsed JSDoc tags */
  tags: TagObject[];
  /** Parsed description with markdown converted to HTML */
  description: {
    full: string;    // Complete description with HTML markup
    summary: string; // First paragraph only
    body: string;    // Remaining paragraphs after summary
  };
  /** True if @api private tag is present */
  isPrivate: boolean;
  /** True if @constructor or @augments tag is present */
  isConstructor: boolean;
  /** True if @class tag is present */
  isClass: boolean;
  /** True if @event tag is present */
  isEvent: boolean;
  /** True if comment starts with /*! (ignored comment) */
  ignore: boolean;
  /** Starting line number of the comment */
  line: number;
  /** Line number where associated code starts */
  codeStart: number;
  /** Code following the comment block */
  code: string;
  /** Parsed context information about the code */
  ctx: ContextObject | null;
}

interface ParseOptions {
  /** Skip markdown processing, leave raw markdown intact */
  raw?: boolean;
  /** Ignore /* ... */ style comments (only process /** ... */ comments) */
  skipSingleStar?: boolean;
  /** Array of comment prefixes to skip (default: ['jslint', 'jshint', 'eshint']) */
  skipPrefixes?: string[];
}