Comment-Preserving Documentation Generator

A tool that compiles CoffeeScript source files while extracting their comments for documentation purposes.

Overview

Build a tool that processes CoffeeScript source code and extracts all comments from it. The tool should compile the code to JavaScript while also capturing both line and block comments with their locations.

Requirements

Input Processing

The tool accepts a CoffeeScript source code string as input.

Comment Extraction

The tool must extract and categorize two types of comments:

• Line comments (single-line comments that start with #)
• Block comments (multi-line comments wrapped with ###)

For each comment, capture:

• The comment text content (without the comment markers)
• The line number where the comment appears in the source code
• The comment type (line or block)

Output Format

The tool should produce a JavaScript object containing:

• The compiled JavaScript code as a string
• An array of comment objects, each with properties: type, text, and line

Test Cases

• Given CoffeeScript code with a single line comment # Calculate sum, the tool returns the compiled JavaScript and a comments array containing one object with type "line", the text "Calculate sum", and the appropriate line number. @test

• Given CoffeeScript code with a block comment ### Multi-line description here ###, the tool returns the compiled JavaScript and a comments array containing one object with type "block" and the full text content. @test

• Given CoffeeScript code with both line and block comments, the tool returns all comments in order of appearance with their correct types and line numbers. @test

• Given CoffeeScript code with no comments, the tool returns the compiled JavaScript and an empty comments array. @test

Implementation

@generates

API

/**
 * Compiles CoffeeScript source and extracts comments
 * @param {string} source - CoffeeScript source code
 * @returns {Object} Object containing compiled JS and extracted comments
 * @returns {string} return.js - Compiled JavaScript code
 * @returns {Array<Object>} return.comments - Array of comment objects
 * @returns {string} return.comments[].type - Comment type: 'line' or 'block'
 * @returns {string} return.comments[].text - Comment text content
 * @returns {number} return.comments[].line - Line number of comment
 */
function compileAndExtractComments(source) {
  // Implementation here
}

module.exports = { compileAndExtractComments };

Dependencies { .dependencies }

coffeescript { .dependency }

Provides CoffeeScript compilation with comment preservation support through the compilation API and token stream access.

@satisfied-by