Repository navigation
Add @arg tag support for documenting excmd flags - #5511
Conversation
Extracts @arg -flag description tags from excmd JSDoc into a flags map in the generated metadata, and renders them as one bullet list in `:help`. A docstring can drop a `{{tridactyl-arg-list}}` marker anywhere in its prose to control where that list renders, since the @arg tags themselves must stay at the end of the comment (TSDoc runs a block tag's content until the next tag). Annotates `hint` as the first user of this new format. Related to tridactyl#5397 (which-key), split out per review discussion since which-key depends on this.
- @Flag text now splits on the first blank line into a short label (shown in the flag list) and longer elaboration prose rendered beneath it. - @endflags closes a run of @Flag tags and flushes them. This prevents TSDoc from swallowing any trailing text into the last @Flag. - Markdown headings inside trailing content are also kept out of the page's sidebar nav to avoid cluttering it with each excmd's subsections.
- Replaces the {{tridactyl-flag-list}} marker and prose flag bullets
with @Flag tags and two @endflags boundaries. This keeps the flags
rendered where they're placed in the code without the rest of the docs
getting swallowed into the last flag's content.
- Moves @PARAM below the content summary to match where the content is
rendered on the Help doc.
- Also fixes -pipe and -W, which had their flag name wrapped in
backticks and were silently dropped by the parser.
Silences the "unknown block tag" warning TypeDoc logged for every @flag/@endflags use, since it didn't recognize them. --blockTags replaces TypeDoc's whole default list rather than appending, so we read the defaults at runtime and re-pass them alongside our two custom tags.
build.sh runs a second, separate typedoc invocation to generate .metadata.generated.json that never got the --blockTags fix from 0b6492b, so it hit the same unknown-tag issue.
This is kind of a hack but I won't lose too much sleep over it
|
i hacked on it to make the renderer detect blank newlines negating the need for if you don't have any strong feelings @uhs-robert i would say this is good to merge |
|
Thanks for adding the tsdoc.json, that's a much smarter approach. As for the hack to get rid of As an aside, for whichkey, I may need to do a sweep of the rest of the excmds to see if we need to add flags anywhere else. Should I make that a seperate PR or tack it onto the whichkey PR? |
|
separate PR i think bonus points if you can at least think about how we might reuse it for excmd completions while you're there :) |
Great idea, I just got excmd completion working locally. I am still tweaking it a bit now. I'm thinking... once this PR gets merged then I'll make another PR specifically for the excmd completion. Then once that is done, I'll focus on a PR to flesh out the rest of the excmds to use the new flag sytem. That way we're building on top of a solid foundation and not having to go back and redo documentation if any changes are needed. |
|
awesome! that was quick :) |
# Release 1.25.1 / 2026-09-08
- New features
- `:tabmove [amount] [index]` added for use primarily in ex-mode binds ([#5045](#5045))
- Bug fixes
- `:mode [custom]` now works again ([#5518](#5518))
- `:mkt` is now noisier about paths and failure
- `:set logging.` works again ([#5513](#5513))
- `searchurls` can now have `%s` in their subdomains ([#5523](#5523))
- Miscellaneous
- noreply email addresses are henceforth banned from commits ([#5517](#5517))
- flag documentation formalised to preserve metadata for eventual reuse ([#5511](#5511))
Thanks to all of our contributors for this release: Oliver Blanthorn, Robert Hill, dependabot[bot] and Marc González Moratona.
Extra special thanks go to Marc González Moratona and Robert Hill who both contributed for the first time.
Last, but not least - thank you to everyone who reported the issues we closed in this release: bovine3dom, pennae, stevium, syntaxenjoyer and veivataan.
Context
This came out of a discussion on #5397 (the which-key PR). The flags for the
hintcommand needed some kind of documented lookup for which-key to use, and rather than adding that onto an already massive PR, this got split out as its own thing.Which-key will build on top of this once it's merged. This PR only touches docs/build tooling, nothing else.
Problem
Right now, the flags for a command like
:hint(i.e.,-t,-b,-y, etc.) are only documented as hand-written notes on the:helppage. There's no way for other code (like which-key) to look up "what does-tdo?" programmatically.So, if a command's flag descriptions ever need to be shown somewhere else, they'd have to be typed out a second time and kept in sync manually.
Solution
This PR adds a simple way to tag each flag right in the code comment like so:
A build script reads these tags and turns them into a small lookup table (flag => description) that which-key,
:help, and anything else can query directly.The
:helppage also needed a small change to handle this well. Out of the box, the docs generator (TypeDoc) treats each@argas its own separate section: a full heading repeated for every single flag (some commands, like hint, have a list of 20+). So, I customized how@argtags get rendered by grouping them into a single bullet list under an "Arguments" heading. I also added a way for whoever writes a command's docs to choose exactly where in the paragraph that list shows up, using a placeholder{{tridactyl-arg-list}}, rather than always having it dumped at the very bottom.Limited Scope
I limited the scope of this PR to just the
hintcommand. Othe 8000 r commands would need the same treatment but before doing any work in that direction, I wanted to see how this would land.Testing
:helppage by hand and confirmedhint's flags show up correctly with the right formatting.Screenshots
This is how the
helppage for thehintcommand looks with this change: