codoc 0.1.0

# 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

```bash
cargo install codoc
```

Or build from source:

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

## Usage

### Parse a Ruby project

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

### Parse a TypeScript project

```bash
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:

```json
{
  "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:

```rust
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