or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

cli-usage.md code-context.md comment-parsing.md documentation-generation.md index.md jsdoc-tags.md

tile.json

Documentation Generation

Convert parsed comment objects into formatted markdown documentation suitable for API reference generation.

Capabilities

API Documentation Generator

Converts an array of parsed comment objects into structured markdown documentation with table of contents and formatted API sections.

/**
 * Generate markdown API documentation from parsed comments
 * @param {CommentObject[]} comments - Array of parsed comment objects from parseComments
 * @returns {string} Formatted markdown documentation with TOC and API sections
 */
function api(comments);

Usage Examples:

const dox = require('dox');
const fs = require('fs');

// Parse a JavaScript file
const source = fs.readFileSync('./mymodule.js', 'utf8');
const comments = dox.parseComments(source);

// Generate markdown documentation
const markdown = dox.api(comments);
console.log(markdown);

// Save to README file
fs.writeFileSync('./README.md', markdown);

// Example output structure:
// - [functionName()](#functionname)
// - [ClassName.method()](#classnamemethodname)
// 
// ### functionName(param1:string, param2:number)
//
// Function description here
//
// ### ClassName.method(args)
//
// Method description here

Generated Documentation Format

The API generator creates markdown with the following structure:

Automatically generated based on detected functions, methods, and classes:

- [add()](#add)
- [User.getName()](#usergetname)
- [Calculator.prototype.multiply()](#calculatorprototypemultiply)

API Sections

Each public API element gets its own section with:

Heading: Function/method signature with parameters and types
Description: Full description from JSDoc comments (converted from HTML)
Code blocks: Automatically formatted with syntax highlighting

Function Signatures

The generator creates readable function signatures from context and tag information:

// Source code:
/**
 * Add two numbers together
 * @param {number} a First number
 * @param {number} b Second number  
 * @return {number} Sum of the numbers
 */
function add(a, b) { return a + b; }

// Generated markdown:
### add(a:number, b:number)

<p>Add two numbers together</p>

Method Signatures

Methods include their full context path:

// Source code:
/**
 * Get user's full name
 * @return {string} The user's full name
 */
User.prototype.getName = function() { return this.name; };

// Generated markdown:
### User.prototype.getName()

<p>Get user's full name</p>

Filtering and Processing

Private API Filtering

The generator automatically filters out private APIs:

Comments marked with @api private are excluded
Comments marked with /*! ... */ (ignored comments) are excluded
Module dependency comments are filtered out
module.exports assignments are filtered out

Description Processing

Comment descriptions are processed for optimal markdown output:

HTML tags from markdown processing are preserved
Code blocks are automatically detected and formatted
Indented code blocks (4+ spaces) are converted to fenced code blocks
Headers are normalized by removing leading # characters

Code Block Enhancement

The generator enhances code blocks with:

Automatic language detection (defaults to js)
Proper fencing with triple backticks
Trimming of excess whitespace
Preservation of indentation structure

Customization and Extension

Template Modification

While dox doesn't provide built-in template customization, you can process the generated markdown:

const dox = require('dox');

// Generate base documentation
const comments = dox.parseComments(source);
const baseMarkdown = dox.api(comments);

// Add custom sections
const customMarkdown = `# My API Documentation

${baseMarkdown}

## Installation

\`npm install my-package\`

## License

MIT License
`;

Custom Processing Pipeline

Create your own documentation generator using dox's parsing capabilities:

const dox = require('dox');

function generateCustomDocs(source) {
  const comments = dox.parseComments(source);
  
  // Filter only public APIs
  const publicApis = comments.filter(comment => !comment.isPrivate);
  
  // Group by type
  const functions = publicApis.filter(c => c.ctx && c.ctx.type === 'function');
  const methods = publicApis.filter(c => c.ctx && c.ctx.type === 'method');
  const classes = publicApis.filter(c => c.ctx && c.ctx.type === 'class');
  
  // Generate custom format
  let docs = '# API Reference\n\n';
  
  if (functions.length) {
    docs += '## Functions\n\n';
    functions.forEach(func => {
      docs += `### ${func.ctx.name}\n\n`;
      docs += `${func.description.full}\n\n`;
    });
  }
  
  if (classes.length) {
    docs += '## Classes\n\n';
    classes.forEach(cls => {
      docs += `### ${cls.ctx.name}\n\n`;
      docs += `${cls.description.full}\n\n`;
    });
  }
  
  return docs;
}

Integration Patterns

Build System Integration

Integrate documentation generation into your build process:

// gulpfile.js or build script
const dox = require('dox');
const fs = require('fs');
const glob = require('glob');

function generateDocs() {
  const jsFiles = glob.sync('./src/**/*.js');
  let allComments = [];
  
  jsFiles.forEach(file => {
    const source = fs.readFileSync(file, 'utf8');
    const comments = dox.parseComments(source);
    allComments = allComments.concat(comments);
  });
  
  const documentation = dox.api(allComments);
  fs.writeFileSync('./docs/API.md', documentation);
}

Static Site Generation

Use dox with static site generators:

// For Jekyll, Hexo, etc.
const dox = require('dox');

function generateForJekyll(source, frontMatter) {
  const comments = dox.parseComments(source);
  const markdown = dox.api(comments);
  
  return `---
${frontMatter}
---

${markdown}`;
}

Output Formatting

Table of Contents Generation

The TOC is generated using internal helper functions:

Extracts headings from generated markdown
Creates anchor links with lowercase, special-character-free slugs
Formats as nested list with consistent indentation

Code Block Processing

Code blocks are enhanced through a multi-step process:

Detection: Identifies indented code blocks (4+ spaces)
Extraction: Removes leading indentation while preserving relative structure
Formatting: Wraps in fenced code blocks with language specification
Replacement: Substitutes original indented blocks with fenced blocks

Link Processing

Internal cross-references and external links are processed:

Heading anchors are automatically generated for all API sections
External URLs in @see tags are preserved as clickable links
Internal references maintain relative linking structure

Error Handling

The documentation generator handles edge cases gracefully:

Empty comment arrays return empty string
Missing context information is skipped rather than causing errors
Malformed HTML in descriptions is passed through as-is
Code blocks with inconsistent indentation are normalized

Version

Tile

Files