How to use AI to convert legacy comments into idiomatic framework documentation

What this does

Legacy codebases often contain inline comments written in prose style that describe behavior, intent, and caveats. This guide explains how to use an AI assistant to parse those comments and generate modern, idiomatic documentation in formats such as JSDoc, Sphinx RST, Markdown README sections, or OpenAPI descriptions. The process extracts meaning from unstructured text and repackages it into structured, machine-readable documentation that frameworks, IDEs, and CI tools can consume directly.

Steps

1. Run a script or manual grep to collect all comment blocks from the target source files into a single text file, preserving the file path and line number for each block.
2. Create a prompt for the AI assistant that includes the target documentation format (e.g., JSDoc), a representative sample of three to five comment blocks, and instructions to produce one structured entry per block.
3. Send the collected comments to the AI assistant with the prompt. Request output in Markdown or JSON lines format, one entry per comment block.
4. Review the generated entries. Check each one for accuracy against the original comment and for alignment with the project's chosen documentation style guide.
5. Write a second AI prompt to split long or multi-topic comments into separate entries and deduplicate near-identical entries across files.
6. Apply the generated entries back into the source files as inline documentation, or merge them into a central documentation file (e.g., docs/api.md).
7. Delete or mark as migrated the original comment blocks that have been successfully converted.

Verification

# Verify new documentation blocks exist in the source tree
grep -r "@param\|@returns\|@throws" --include="*.py" --include="*.js" . | wc -l
# Expected: integer greater than 0; count reflects new structured doc entries

Common failures

• Comment blocks are too terse or contain placeholder text. AI output will reflect poor input quality. Pre-process sparse comments by adding context before sending to the AI.
• Generated JSDoc does not match project conventions. Run a linter (ESLint with JSDoc rules, or pydocstyle) on the output to surface mismatches early.
• Original comments were not removed, creating duplication. Use a diff tool to compare the before and after state and explicitly delete migrated comment lines.
• AI model pads output with explanations instead of clean doc blocks. Refine the prompt with a zero-shot instruction such as "Return Markdown code blocks only. No preamble."
• Version mismatch - The installed package or runtime differs from the command shown; check the version first and rerun the smallest verification command.
• Local environment drift - Another service, virtual environment, model, or path is being used; print the active binary path and configuration before changing the guide steps.

Related guides

• Integrate an AI assistant into your API client library to auto-generate usage examples
• Use AI to transform legacy API response schemas into modern typed structures