feat: Workflow for generating JSDoc comments / documentation

[madjin]

Is your feature request related to a problem? Please describe.
Currently, maintaining comprehensive JSDoc documentation across our TypeScript codebase is a manual and time-consuming process. This leads to inconsistent documentation coverage and puts an unnecessary burden on developers. We need an automated solution that can help generate and maintain JSDoc comments while ensuring high quality and consistency.

Describe the solution you'd like

Propose a two-phase approach:

1. Manual Documentation Phase:

   • Add comprehensive JSDoc comments to all TypeScript files
   • Include documentation for functions, classes, interfaces, and other code blocks

2. Automation Implementation:

   • Develop an LLM-based automation solution for generating JSDoc comments
   • Integrate the automation into our CI/CD pipeline (like when a PR for a new feat is merged)
   • Create a manual trigger mechanism for the automation process

Create a GitHub Actions workflow/AI agent that:

1. Automated Documentation Generation:

   • Triggers on demand (via workflow_dispatch) or when specific files change
   • Scans TypeScript files that lack JSDoc documentation
   • Uses an AI service (e.g., OpenAI API) to generate contextually accurate JSDoc comments
   • Maintains existing JSDoc comments and only adds missing ones

2. Quality Control:

   • Follows our existing JSDoc standards and TypeDoc configuration
   • Validates generated comments for completeness and accuracy
   • Ensures proper documentation of parameters, return types, and function descriptions

3. Pull Request Management:

   • Creates a new branch for documentation updates
   • Generates a pull request with the changes
   • Adds appropriate labels (e.g., 'documentation', 'automated')
   • Includes a detailed PR description explaining the changes
   • Assigns relevant reviewers

4. Configuration:

   • Allows customization of AI prompt templates
   • Provides options to include/exclude specific files or directories
   • Configurable commit message and PR templates

Describe alternatives you've considered

1. Manual documentation enforcement through PR checks
2. Using existing JSDoc generation tools like https://github.com/TypeStrong/typedoc
3. Implementing stricter code review policies for documentation
4. Creating documentation sprints for batch updates

Additional context
Required Permissions and Secrets:

• GitHub token with PR creation permissions
• AI service API key (e.g., OpenAI)
• Repository write access for branch creation

Additional Motivation

This could be a proof of concept AI junior dev Karpathy talks about

[0xbuild-oss]

I can pick this up. Hmu on discord @0xbuildinpublic if interested in helping.

[ileana-pr]

I am beginner coder but I can help with menial tasks like the manual phase while we get the automation up an running.

[0xbuild-oss]

Progress can be checked in this repo:
https://github.com/AudixAI/plugin-audix

[0xbuild-oss]

Doing some clean up then opening the PR tomorrow

[madjin]

There's now an awesome PR for agentic JSdocs documentation via github actions. This could help us generate better API docs with the typedoc-markdown-docusuarus plugin as seen here: https://ai16z.github.io/eliza/api/

Here is a screenshot of how it looks in practice: https://github.com/AudixAI/eliza/pulls

I find the API docs useful when prompting, other devs already have all this functionality in their IDE. It's been said that more commented code improves the generation.

I've gotten some feedback about how comments might get in the way of reading the code. My response to that was if it becomes an issue, then could we have a branch where the code is commented thoroughly for API docs generatoin? Or maybe there's a workflow for people to hide comments easily? Any thoughts?

[Ed-Marcavage]

Yes I could easily add a boolean flag in the workflow that removes any pre-existing JSDoc instead of generating it:

https://github.com/ai16z/eliza/pull/1343/files#diff-4f536c46941954320665653b90d4e940bf21a65dbc4268d8a0d2dc0af8beca78R186

Also in the future I could add "Improve/Edit mode" that takes a specific prompt & scans all preexisting JSDoc to modify them in some way - maybe different languages (Spanish, Mandarin, ect.) 🤔 or just make them all more/less verbose.

[Ed-Marcavage]

Also, IMO, having JSDoc or at least a branch that's fully JSDoc'd will make things like this easier in the future:
"generate HowTo, FAQ, Tutorial, and other custom pages" as seen here:
https://github.com/ingig/code-narrator/tree/master/docs

[madjin]

Those are all great ideas! Shaw is excited, I am too. Will do some testing

[monilpat]

I think this might be able to be closed @madjin :)