codoc

A unified documentation parser for Ruby and TypeScript codebases. Extracts documentation comments (Yardoc for Ruby, JSDoc/TypeDoc for TypeScript) and outputs a common JSON format.

Features

• Parse Ruby files with Yardoc-style comments
• Parse TypeScript files with JSDoc/TypeDoc-style comments
• Unified JSON output format for cross-language documentation
• Extract classes, modules, interfaces, methods, properties, and more
• Support for type parameters, generics, and complex type references
• Symbol table generation for cross-referencing

Installation

cargo install codoc

Or build from source:

git clone https://github.com/sudoremo/codoc
cd codoc
cargo build --release

Usage

Parse a Ruby project

codoc parse ./src -l ruby -n "MyProject" -o docs.json

Parse a TypeScript project

codoc parse ./src -l typescript -n "MyProject" -o docs.json

Options

Usage: codoc parse [OPTIONS] -l <LANGUAGE> <PATH>

Arguments:
  <PATH>  Source directory or file to parse

Options:
  -o, --output <OUTPUT>      Output file path (defaults to stdout)
  -l, --language <LANGUAGE>  Source language [possible values: ruby, typescript]
  -n, --name <NAME>          Project name [default: project]
      --version <VERSION>    Project version
      --id-prefix <PREFIX>   ID prefix for all entities
      --pretty               Pretty-print JSON output [default: true]
  -h, --help                 Print help

Output Format

The parser outputs JSON conforming to the codoc schema. See doc/SCHEMA.md for the full specification.

Example output structure:

{
  "schema": "codoc/v1",
  "metadata": {
    "name": "MyProject",
    "language": "ruby",
    "generatedAt": "2025-01-01T00:00:00Z",
    "files": ["lib/my_class.rb"]
  },
  "entities": [
    {
      "kind": "class",
      "id": "MyClass",
      "name": "MyClass",
      "docs": {
        "summary": "A sample class."
      },
      "methods": [...]
    }
  ],
  "symbols": [...]
}

Supported Documentation Tags

Ruby (Yardoc)

• @param - Parameter documentation
• @option - Hash option documentation
• @return - Return value documentation
• @raise - Exception documentation
• @yield, @yieldparam, @yieldreturn - Block documentation
• @example - Code examples
• @see - Cross-references
• @note - Important notes
• @todo - TODO items
• @deprecated - Deprecation notices
• @since - Version information
• @author - Author attribution

TypeScript (JSDoc/TypeDoc)

• @param - Parameter documentation
• @returns / @return - Return value documentation
• @throws / @throw - Exception documentation
• @example - Code examples
• @see - Cross-references
• @todo - TODO items
• @deprecated - Deprecation notices
• @since / @version - Version information
• @template - Type parameter documentation
• @private / @internal - Visibility markers

Library Usage

You can also use codoc as a library:

use codoc::parser::ruby::RubyParser;
use codoc::parser::{Parser, ParserConfig, ParseContext};
use codoc::schema::Language;

let mut parser = RubyParser::new()?;
let config = ParserConfig::new("MyProject", Language::Ruby);
let mut ctx = ParseContext::new(config);

let entities = parser.parse_file(&path, &content)?;
ctx.entities.extend(entities);

let document = ctx.into_document();

License

MIT