How fynnfluegge/doc-comments-ai works
Project type and purpose
• This is an open-source, CLI-based developer tool (Python package) that generates documentation comments for source files using LLMs and Tree-sitter.
• Key use case: “aicomment <path>” parses your code, sends method signatures and bodies to an LLM (OpenAI/Azure or local via llama.cpp/ollama), and injects generated doc blocks back into the file.
Main components
a. CLI entrypoint
• __main__.py / app.py
• Parses command-line options, resolves flags (–inline, –guided, –gpt4, –local_model, etc.)
b. Core application logic
• app.py: orchestrates file I/O, change detection (unstaged changes check), Treesitter parsing, LLM invocation, and patch application.
• constants.py, utils.py: helper functions and shared constants.
c. Treesitter integration
• treesitter/treesitter.py & per-language modules (treesitter_c.py, treesitter_py.py, …)
• treesitter_registry.py: plugin registry that picks the right parser based on file extension.
d. LLM interface
• llm.py: abstraction over multiple backends
• OpenAI (GPT-3.5/Turbo, GPT-4)
• Azure OpenAI
• Local llama.cpp (via llama-cpp-python)
• Local Ollama
e. File system & patching
• Reads source files, generates AST, extracts method definitions, writes back with inserted docstrings.
f. Tests & CI
• tests/: unit tests for parser logic and response parsing.
• GitHub workflows: build and publish pipelines.
Relationships and data flow
1) User issues CLI command →
2) CLI parser loads app.py →
3) app.py invokes Tree-sitter registry to parse file →
4) Extracted code segments passed to llm.py →
5) llm.py sends prompt to selected LLM backend →
6) LLM returns doc comments →
7) app.py applies comments to in-memory AST or text buffer →
8) Writes patched file back to disk.
External dependencies: OpenAI/Azure endpoints or local models (llama.cpp/ollama).
Architectural patterns & design principles
• Plugin/strategy pattern for Treesitter language support.
• Adapter pattern for multiple LLM backends behind a single interface.
• Single-responsibility modules: CLI, parsing, LLM communication, utilities.
• Pure-Python CLI application—no frontend or database.