Generate Messenger API documentation

[desi]

Problem

To make the Wallet Framework a success, we want developers to use the messenger within the UI and other places. However, currently, it is very difficult for them to understand what sorts of actions and events are available, and it is even more difficult to understand what each action and event does.

Solution

To fix this, we want to build a live-updating documentation system for each client that listens for a new commit, looks at the messenger actions and events present in the global messenger, collects their TSDoc/JSDoc blocks from the packages where those actions and events come from, and organizes them into a site. A new version of this site should be deployed for each commit in the repo.

The goal of this ticket is to work out a POC that operates on the messenger actions and events available across packages in this monorepo and to work out how the site should be automatically built and deployed.

Acceptance Criteria

• When a new commit shows up on main, JSDoc blocks for all messenger action and event types across all packages in the monorepo should be collected and compiled into a site, which should be deployed to GitHub Pages
• When a new commit shows up in a pull request, the same thing should happen, but the site should be stored in an artifact. The user can then download the artifact to load the docsite locally.

[mcmire]

Marking as "needs refinement" due to the comment above. We need to identify the problem being solved here and ensure that we understand how this fits into the Wallet Framework project.

[cryptodev-2s]

📖 Messenger API Documentation Process (POC)

We’re setting up a process to generate centralized, searchable documentation for all Messenger-related actions and events defined across the core monorepo (for POC then we will make it broadly usable).

✅ What This Will Do • Automatically extract all JSDoc comments related to Messenger actions and events (e.g., messages between controllers) • Aggregate this documentation across all packages in the workspace • Generate a single, browsable documentation site per controller using Docusaurus • Keep the documentation live-updated as the code evolves (locally and in CI)

🧰 Tools We’ll Use • TypeDoc – to extract JSDoc comments from TypeScript • typedoc-plugin-markdown – to convert the extracted API docs into Markdown • Docusaurus – to render the Markdown content as a searchable, user-friendly HTML site • Custom script – to scan all packages and extract only Messenger-related items (e.g. actions, events) • CI integration – to ensure docs stay in sync with code changes

🎯 Why We’re Doing This • Improve discoverability and transparency of inter-controller messaging • Make the internal Messenger API easier to explore and maintain • Encourage better inline documentation across the codebase

This will serve as a living reference for Messenger-based communication across all MetaMask packages.

[mcmire]

I believe documenting all of the messenger actions and events within core controllers can already be achieved by https://github.com/MetaMask/core/issues/1845.

Based on conversations I've had with Mark, my impression was that we needed to document the actions and events of the controllers that both extension and mobile are using currently, not all of the controllers that exist in core (or elsewhere). So the documentation would actually live within the clients, and not core. Does that sound right to you @Gudahtt?

[Gudahtt]

Yes exactly.

The docs would be generated based on the global messenger instance in the clients (e.g. so there'd be a 1:1 correspondence between a given client commit and a given version of the generated docs). It may or may not be stored/hosted in the client repo, but there should be a correspondence at least.

[Gudahtt]

The inline TSDoc blocks we're generating the docs from are in multiple repositories though. Those aren't accessible just from the client because the comments aren't even in the build output right now, they're not in the package. So we do need to use the core repo directly when generating these docs, even if we're generating them for a client.

I believe that was the basis for @cryptodev-2s focusing just on core with the POC.

[mcmire]

@Gudahtt and I talked more about this today. I believe I have more of an understanding of how we are approaching this ticket. Here are some notes I made:

• The problem we are trying to solve is that currently, knowing what the platform will do and knowing what each action and event does is hidden in the code. We want to make these discoverable.
• The final product will be generated documentation in the extension and mobile repos (or something similar — this can be worked out later).
  • This will include whatever capabilities the global messenger has, per client, at any given time.
  • Although we may have actions and events grouped together by delegated messenger, we don't need the documentation to reflect this grouping.
• How would the documentation be used?
  • The scenario is that I'm a engineer, I want to build out a feature, and now I want to wire up the UI. I'm told that I need to use the messenger to call actions. Assuming that the global messenger has the actions I need, and that if there is a delegated messenger it has what I need too, I go to the documentation site that lists all messenger actions that are available. Each one has a description of what the action does, and I use this to know what to call.
  • There may be a scenario that involves events as well, but those would probably be used differently than actions.
• Would reviving automatic generation/publishing of API documentation for all packages using typedoc solve the problem?
  • We need something that lists what the platform does in a clear manner, and the way that typedoc works and organizes the generated documentation wouldn't help us do that.
• The goal of the POC that was mentioned above is mainly to work out the implementation details. Even though we will eventually want to base the docs on exact versions of packages used in the clients, we don't need to do that now, we can do all the work in the core repo and pretend that we are in the client, because the work will be the same.

[mcmire]

We also talked through some implementation details/ideas, and this is a bit more actionable/relevant:

• The Messenger API documentation could work similar to the TypeScript migration dashboard in the extension. In this case, there are two kinds of builds we could generate: one for commits in PRs, another for commits to main. For commits in PRs, the build could be stored and accessible via an artifact (we could automatically a post a comment when the build is complete and provide a link to the artifact). For commits on main, the build could be stored in a separate repo and published to GitHub Pages (i.e., the GitHub Pages version would always reflect the latest changes to main).
• As for how exactly we generate the documentation, well, this is what the POC is designed to work out. We need to be able to essentially read the type definitions in pre-built code in node_modules, extract the JSDoc blocks for messenger actions and events only, organize them into something that makes sense, and then generate an HTML version. Using typedoc combined with typedoc-plugin-markdown does seem like a good approach, but maybe there is another way?
  • Microsoft has some tools around API doc generation too, most notably API Extractor, so maybe that could work if typedoc doesn't give us the customization we need? Just an idea.

[mcmire]

I've updated the PR description to match our discussion. Let me know if that is clear enough or if there are any other details we need to add.

[mcmire]

Will be estimated after getting into the work a bit.

[mcmire]

.@cryptodev-2s is OOO currently. Moving back to "ready for dev" so we can represent that.