Block2Docs

Transforming DocBlocks into Documentation Workflows with AI

Documentation is the easy part—knowing what to document and how is the hard part. For every WordPress release, going through all Trac and GitHub tickets, labelling those that need documentation, and creating issues is a two-week job for a single person. A manual job that should never be done manually.

Block2Docs is a hybrid tool that bridges the gap between code and documentation by combining intelligent DocBlock parsing with AI-powered content generation. It reads annotations from your code to identify what needs documentation, uses AI to generate content, and routes everything to the appropriate output—changelog entries, GitHub issues, API references, field guides, and more.

Parser/Workflow Engine

The core parser scans PHP/JavaScript code, extracting DocBlocks and documentation, and needs to:

• Generate API Docs: Create structured API documentation from inline comments.
• Generate Changelogs: Extract version history from @since and @changelog tags.
• Structure Field Guides: Automatically build release documentation frameworks.
• Create GitHub Issues: Generate issues for items tagged @needs-docs, routed by doc type (dev note, end-user guide, how-to, tutorial).

AI Content Generation

The AI drafts missing or incomplete documentation:

• Draft Descriptions: Generate meaningful descriptions for undocumented functions, classes, and methods.
• Detect Drift: Identify when code changes make existing documentation stale.
• Build Context: Understand codebase patterns for consistent, project-appropriate documentation.

Flexible Configuration

• Config-driven: Use YAML/JSON for easy project customization.
• Template System: Extensible templates; override defaults or create new ones.
• Language Agnostic: Starts with PHP/JavaScript; architecture supports future languages.
• CI/CD Ready: Integrates into existing development pipelines.

Target Audience

• PHP Developers: Build the DocBlock parser for PHP, leveraging the PHPDocumentor libraries and handling WordPress-specific annotations such as hooks, actions, and filters.
• JavaScript/TypeScript Developers: Implement the JS/TS parsing layer, handle JSDoc annotations, and build the CLI interface.
• AI/LLM Enthusiasts: Design the AI content generation pipeline, implement drift detection, and optimize prompts for documentation-specific outputs.
• DevOps/CI Engineers: Create a GitHub Actions integration, design the issue-creation workflow, and build the template routing system.
• Technical Writers: Define documentation type taxonomies, create issue templates, and ensure generated content follows documentation best practices.

Hackathon Goals

1. Develop a working CLI to parse PHP/JS annotations, extracting structured DocBlock data for documented and undocumented code.
2. Implement automated changelog generation using @since and @changelog tags, with fallback to git history for untagged changes.
3. Create a GitHub issue workflow for @needs-docs items that generates templated issues for documentation requirements (dev, user, guide).
4. Integrate AI to draft descriptions for undocumented functions, using an LLM for inline DocBlocks and external docs.
5. Design a flexible configuration system for customizing parsing, output, templates, and AI behaviour.
6. Produce a compelling demo on a real codebase (e.g., WordPress plugin), showcasing the full scanning-to-documentation/issue pipeline.