From e744f5651de8ccfd04ac2bb75ece52074af53d84 Mon Sep 17 00:00:00 2001 From: Robert Hill Date: Thu, 27 Aug 2026 14:44:07 -0400 Subject: [PATCH] Rename @arg tag to @flag @arg is a bit ambiguous since an "argument" can hold anything. @flag better matches what this tag actually documents (excmd command-line flags). --- scripts/convert_typedoc_metadata.js | 4 +- scripts/typedoc-theme.mjs | 28 ++++++------ src/excmds.ts | 66 ++++++++++++++--------------- 3 files changed, 49 insertions(+), 49 deletions(-) diff --git a/scripts/convert_typedoc_metadata.js b/scripts/convert_typedoc_metadata.js index f9f7fc52..32accfbd 100644 --- a/scripts/convert_typedoc_metadata.js +++ b/scripts/convert_typedoc_metadata.js @@ -32,11 +32,11 @@ function convertMetadata(project) { .map(part => part.text || "") .join("") .replace(/\n+$/, "") - // Extract @arg tags: `@arg -flag description` -> flags["-flag"] = "description" + // Extract @flag tags: `@flag -flag description` -> flags["-flag"] = "description" const argFlags = comment => { const flags = {} for (const tag of comment?.blockTags || []) { - if (tag.tag !== "@arg") continue + if (tag.tag !== "@flag") continue const text = (tag.content || []).map(part => part.text || "").join("") const m = /^(-\S+)\s+(.+)$/.exec(text.trim()) if (m) flags[m[1]] = m[2] diff --git a/scripts/typedoc-theme.mjs b/scripts/typedoc-theme.mjs index 94b3c59e..8d31c6fa 100644 --- a/scripts/typedoc-theme.mjs +++ b/scripts/typedoc-theme.mjs @@ -252,21 +252,21 @@ class TridactylRouter extends KindRouter { } } -function parseArgTag(tag) { +function parseFlagTag(tag) { const text = (tag.content || []).map(part => part.text || "").join("") const m = /^(-\S+)\s+(.+)$/.exec(text.trim()) return m ? [m[1], m[2]] : undefined } -function renderArgList(anchor, parsed) { +function renderFlagList(anchor, parsed) { if (parsed.length === 0) return null return h( "div", - { class: "tsd-tag-arg tsd-comment tsd-typography" }, + { class: "tsd-tag-flag tsd-comment tsd-typography" }, h( "h4", { class: "tsd-anchor-link", id: anchor }, - "Arguments", + "Flags", h( "a", { href: `#${anchor}`, "aria-label": "Permalink", class: "tsd-anchor-icon" }, @@ -285,7 +285,7 @@ function renderArgList(anchor, parsed) { ) } -const ARG_MARKER = "{{tridactyl-arg-list}}" +const FLAG_MARKER = "{{tridactyl-flag-list}}" class TridactylTheme extends DefaultTheme { getRenderContext(page) { @@ -293,22 +293,22 @@ class TridactylTheme extends DefaultTheme { const defaultCommentSummary = context.commentSummary context.commentSummary = props => { const owner = props.isParameter?.() ? props.parent : props - const argTags = (owner?.comment?.blockTags || []).filter( - tag => tag.tag === "@arg", + const flagTags = (owner?.comment?.blockTags || []).filter( + tag => tag.tag === "@flag", ) const summaryParts = props.comment?.summary || [] const markerIndex = summaryParts.findIndex( - part => part.kind === "text" && part.text.includes(ARG_MARKER), + part => part.kind === "text" && part.text.includes(FLAG_MARKER), ) - if (argTags.length === 0 || markerIndex === -1) + if (flagTags.length === 0 || markerIndex === -1) return defaultCommentSummary(props) - argTags.forEach(tag => (tag.skipRendering = true)) - const parsed = argTags.map(parseArgTag).filter(Boolean) - const anchor = `${String(owner.name || "arguments").toLowerCase()}-arguments` + flagTags.forEach(tag => (tag.skipRendering = true)) + const parsed = flagTags.map(parseFlagTag).filter(Boolean) + const anchor = `${String(owner.name || "flags").toLowerCase()}-flags` const markerPart = summaryParts[markerIndex] - const [beforeText, afterText] = markerPart.text.split(ARG_MARKER) + const [beforeText, afterText] = markerPart.text.split(FLAG_MARKER) const before = [ ...summaryParts.slice(0, markerIndex), ...(beforeText ? [{ kind: "text", text: beforeText }] : []), @@ -321,7 +321,7 @@ class TridactylTheme extends DefaultTheme { JSX.Fragment, null, before.length > 0 && context.displayParts(before), - renderArgList(anchor, parsed), + renderFlagList(anchor, parsed), after.length > 0 && context.displayParts(after), ) } diff --git a/src/excmds.ts b/src/excmds.ts index dfa14f26..68474c1c 100644 --- a/src/excmds.ts +++ b/src/excmds.ts @@ -5532,7 +5532,7 @@ const KILL_STACK: Element[] = [] * * Hinting action flags (only one can be specified): * - * {{tridactyl-arg-list}} + * {{tridactyl-flag-list}} * * - `-pipe selector key` e.g, `-pipe a href` returns the URL of the chosen link on a page. Only makes sense with `composite`, e.g, `composite hint -pipe .some-class>a textContent | yank`. If you don't select a hint (i.e. press ``), will return an empty string. Most useful when used like `-c` to do things other than opening links. NB: the query selector cannot contain any spaces. * - `-W excmd...` pass hint href as the final argument to excmd and execute, e.g, `hint -W mpvsafe` to open YouTube videos. NB: passing it to bare [[exclaim]] is dangerous - see `get exaliases.mpvsafe` for an example of how to do it safely. The usual [[composite]] caveats for `;` and `|` in URLs apply. If you need to use a query selector, use `-pipe` instead. @@ -5603,38 +5603,38 @@ const KILL_STACK: Element[] = [] * * NB: by default, hinting respects whether links say they should be opened in new tabs (i.e. `target=_blank`). If you wish to override this you can use `:hint -JW open` to force the hints to open in the current tab. JavaScript hints (grey ones) will always open wherever they want, but if you want to include these anyway you can use `:hint -W open`. * - * @arg -t open in a new foreground tab - * @arg -b open in background - * @arg -y copy (yank) link's target to clipboard - * @arg -p copy an element's text to the clipboard - * @arg -h select an element (as if you click-n-dragged over it) - * @arg -P copy an element's title/alt text to the clipboard - * @arg -r read an element's text with text-to-speech - * @arg -i view an image - * @arg -I view an image in a new tab - * @arg -k irreversibly deletes an element from the page (until reload) - * @arg -K hides an element on the page; hidden elements can be restored using elementunhide - * @arg -s save (download) the linked resource - * @arg -S save the linked image - * @arg -a save-as the linked resource - * @arg -A save-as the linked image - * @arg -; focus an element and set it as the element or the child of the element to scroll - * @arg -# yank an element's anchor URL to clipboard - * @arg -w open in new window - * @arg -wp open in new private window - * @arg -z scroll an element to the top of the viewport - * @arg -pipe pipe attribute to clipboard - * @arg -W run excmd with hint href - * @arg -F run JS callback - * @arg -c hint CSS selector only - * @arg -C hint CSS selector and defaults - * @arg -x exclude CSS selector - * @arg -f filter hints by text - * @arg -fr filter hints by regex - * @arg -J disable JS hints - * @arg -V include invisible elements - * @arg -q rapid (stay in hint mode) - * @arg -! execute all hints immediately + * @flag -t open in a new foreground tab + * @flag -b open in background + * @flag -y copy (yank) link's target to clipboard + * @flag -p copy an element's text to the clipboard + * @flag -h select an element (as if you click-n-dragged over it) + * @flag -P copy an element's title/alt text to the clipboard + * @flag -r read an element's text with text-to-speech + * @flag -i view an image + * @flag -I view an image in a new tab + * @flag -k irreversibly deletes an element from the page (until reload) + * @flag -K hides an element on the page; hidden elements can be restored using elementunhide + * @flag -s save (download) the linked resource + * @flag -S save the linked image + * @flag -a save-as the linked resource + * @flag -A save-as the linked image + * @flag -; focus an element and set it as the element or the child of the element to scroll + * @flag -# yank an element's anchor URL to clipboard + * @flag -w open in new window + * @flag -wp open in new private window + * @flag -z scroll an element to the top of the viewport + * @flag -pipe pipe attribute to clipboard + * @flag -W run excmd with hint href + * @flag -F run JS callback + * @flag -c hint CSS selector only + * @flag -C hint CSS selector and defaults + * @flag -x exclude CSS selector + * @flag -f filter hints by text + * @flag -fr filter hints by regex + * @flag -J disable JS hints + * @flag -V include invisible elements + * @flag -q rapid (stay in hint mode) + * @flag -! execute all hints immediately */ //#content export async function hint(...args: string[]): Promise {