firefox/tridactyl.tridactyl
1
0
Fork 0
mirror of https://github.com/tridactyl/tridactyl.git synced 2026-09-10 07:16:33 -04:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Rename @arg tag to @flag

Browse source 
@arg is a bit ambiguous since an "argument" can hold anything.

@flag better matches what this tag actually documents (excmd
command-line flags).
This commit is contained in:
Robert Hill 2026-08-27 14:44:07 -04:00
parent a7d6115688
commit e744f5651d
3 changed files with 49 additions and 49 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
scripts/convert_typedoc_metadata.js
View file

@ -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]

28
scripts/typedoc-theme.mjs
View file

@ -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),
)
}

66
src/excmds.ts
View file

@ -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 `<Esc>`), 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<any> {