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 || "") .map(part => part.text || "")
.join("") .join("")
.replace(/\n+$/, "") .replace(/\n+$/, "")
// Extract @arg tags: `@arg -flag description` -> flags["-flag"] = "description" // Extract @flag tags: `@flag -flag description` -> flags["-flag"] = "description"
const argFlags = comment => { const argFlags = comment => {
const flags = {} const flags = {}
for (const tag of comment?.blockTags || []) { 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 text = (tag.content || []).map(part => part.text || "").join("")
const m = /^(-\S+)\s+(.+)$/.exec(text.trim()) const m = /^(-\S+)\s+(.+)$/.exec(text.trim())
if (m) flags[m[1]] = m[2] 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 text = (tag.content || []).map(part => part.text || "").join("")
const m = /^(-\S+)\s+(.+)$/.exec(text.trim()) const m = /^(-\S+)\s+(.+)$/.exec(text.trim())
return m ? [m[1], m[2]] : undefined return m ? [m[1], m[2]] : undefined
} }
function renderArgList(anchor, parsed) { function renderFlagList(anchor, parsed) {
if (parsed.length === 0) return null if (parsed.length === 0) return null
return h( return h(
"div", "div",
{ class: "tsd-tag-arg tsd-comment tsd-typography" }, { class: "tsd-tag-flag tsd-comment tsd-typography" },
h( h(
"h4", "h4",
{ class: "tsd-anchor-link", id: anchor }, { class: "tsd-anchor-link", id: anchor },
"Arguments", "Flags",
h( h(
"a", "a",
{ href: `#${anchor}`, "aria-label": "Permalink", class: "tsd-anchor-icon" }, { 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 { class TridactylTheme extends DefaultTheme {
getRenderContext(page) { getRenderContext(page) {
@ -293,22 +293,22 @@ class TridactylTheme extends DefaultTheme {
const defaultCommentSummary = context.commentSummary const defaultCommentSummary = context.commentSummary
context.commentSummary = props => { context.commentSummary = props => {
const owner = props.isParameter?.() ? props.parent : props const owner = props.isParameter?.() ? props.parent : props
const argTags = (owner?.comment?.blockTags || []).filter( const flagTags = (owner?.comment?.blockTags || []).filter(
tag => tag.tag === "@arg", tag => tag.tag === "@flag",
) )
const summaryParts = props.comment?.summary || [] const summaryParts = props.comment?.summary || []
const markerIndex = summaryParts.findIndex( 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) return defaultCommentSummary(props)
argTags.forEach(tag => (tag.skipRendering = true)) flagTags.forEach(tag => (tag.skipRendering = true))
const parsed = argTags.map(parseArgTag).filter(Boolean) const parsed = flagTags.map(parseFlagTag).filter(Boolean)
const anchor = `${String(owner.name || "arguments").toLowerCase()}-arguments` const anchor = `${String(owner.name || "flags").toLowerCase()}-flags`
const markerPart = summaryParts[markerIndex] const markerPart = summaryParts[markerIndex]
const [beforeText, afterText] = markerPart.text.split(ARG_MARKER) const [beforeText, afterText] = markerPart.text.split(FLAG_MARKER)
const before = [ const before = [
...summaryParts.slice(0, markerIndex), ...summaryParts.slice(0, markerIndex),
...(beforeText ? [{ kind: "text", text: beforeText }] : []), ...(beforeText ? [{ kind: "text", text: beforeText }] : []),
@ -321,7 +321,7 @@ class TridactylTheme extends DefaultTheme {
JSX.Fragment, JSX.Fragment,
null, null,
before.length > 0 && context.displayParts(before), before.length > 0 && context.displayParts(before),
renderArgList(anchor, parsed), renderFlagList(anchor, parsed),
after.length > 0 && context.displayParts(after), 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): * 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. * - `-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. * - `-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`. * 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 * @flag -t open in a new foreground tab
* @arg -b open in background * @flag -b open in background
* @arg -y copy (yank) link's target to clipboard * @flag -y copy (yank) link's target to clipboard
* @arg -p copy an element's text to the clipboard * @flag -p copy an element's text to the clipboard
* @arg -h select an element (as if you click-n-dragged over it) * @flag -h select an element (as if you click-n-dragged over it)
* @arg -P copy an element's title/alt text to the clipboard * @flag -P copy an element's title/alt text to the clipboard
* @arg -r read an element's text with text-to-speech * @flag -r read an element's text with text-to-speech
* @arg -i view an image * @flag -i view an image
* @arg -I view an image in a new tab * @flag -I view an image in a new tab
* @arg -k irreversibly deletes an element from the page (until reload) * @flag -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 * @flag -K hides an element on the page; hidden elements can be restored using elementunhide
* @arg -s save (download) the linked resource * @flag -s save (download) the linked resource
* @arg -S save the linked image * @flag -S save the linked image
* @arg -a save-as the linked resource * @flag -a save-as the linked resource
* @arg -A save-as the linked image * @flag -A save-as the linked image
* @arg -; focus an element and set it as the element or the child of the element to scroll * @flag -; 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 * @flag -# yank an element's anchor URL to clipboard
* @arg -w open in new window * @flag -w open in new window
* @arg -wp open in new private window * @flag -wp open in new private window
* @arg -z scroll an element to the top of the viewport * @flag -z scroll an element to the top of the viewport
* @arg -pipe pipe attribute to clipboard * @flag -pipe pipe attribute to clipboard
* @arg -W run excmd with hint href * @flag -W run excmd with hint href
* @arg -F run JS callback * @flag -F run JS callback
* @arg -c hint CSS selector only * @flag -c hint CSS selector only
* @arg -C hint CSS selector and defaults * @flag -C hint CSS selector and defaults
* @arg -x exclude CSS selector * @flag -x exclude CSS selector
* @arg -f filter hints by text * @flag -f filter hints by text
* @arg -fr filter hints by regex * @flag -fr filter hints by regex
* @arg -J disable JS hints * @flag -J disable JS hints
* @arg -V include invisible elements * @flag -V include invisible elements
* @arg -q rapid (stay in hint mode) * @flag -q rapid (stay in hint mode)
* @arg -! execute all hints immediately * @flag -! execute all hints immediately
*/ */
//#content //#content
export async function hint(...args: string[]): Promise<any> { export async function hint(...args: string[]): Promise<any> {