docs: tag names and content

Signed-off-by: Lexus Drumgold <unicornware@flexdevelopment.llc>
flex-development · Apr 12, 2024 · 7c4355b · 7c4355b
1 parent 7a7c60d
commit 7c4355b
Show file tree

Hide file tree

Showing 3 changed files with 24 additions and 6 deletions.
diff --git a/README.md b/README.md
@@ -165,6 +165,10 @@ interface BlockTag extends Parent, Tag {
 
 **BlockTag** ([**Parent**](#parent)) represents top-level metadata.
 
+Block tags should be the only element on their line, except in cases where special meaning is assigned to succeeding
+text. All text following a block [tag name](#tagname), up until the start of the next block tag name, or comment closer
+(`*/`), is considered to be the block tag's [*tag content*](#tag-content).
+
 **BlockTag** can be used in [**comment**](#comment) nodes. Its content model is [**block tag**](#blocktagcontent)
 content.
 
@@ -234,6 +238,9 @@ interface InlineTag extends Literal, Tag {
 
 **InlineTag** ([**Literal**](#literal)) represents inline metadata.
 
+Inline tags are denoted by wrapping a [tag name](#tagname) and any [*tag content*](#tag-content) in angle brackets (`{`
+and `}`).
+
 **InlineTag** can be used in [**block tag**](#blocktag) and [**description**](#description) nodes. It cannot contain any
 children &mdash; it is a [*leaf*][unist-leaf].
 
@@ -278,9 +285,15 @@ interface Tag {
 
 **Tag** represents metadata associated with a [**comment**](#comment).
 
-The `name` field represents the tag name. Tag names start with an at-sign (`@`) and may contain any ASCII letters after
+The `name` field represents the tag name. Tag names start with an at-sign (`@`) and may contain any ASCII letter after
 the at-sign.
 
+#### `TagName`
+
+```ts
+type TagName<T extends string = string> = `@${T}`
+```
+
 ## Content model
 
 ```ts
@@ -340,6 +353,11 @@ See the [unist glossary][unist-glossary] for more terms.
 A specially formatted [comment][wiki-comment] in a source [*file*][unist-file] used to document a segment of code or
 provide additional information.
 
+### Tag content
+
+Any text following a [block tag](#blocktag) name (e.g. `@example`, `@param`), up until the start of the next block tag
+or comment closer (`*/`), or any text following an [inline tag](#inlinetag) name, up until the closing punctuator (`}`).
+
 ## List of utilities
 
 See the [unist list of utilities][unist-utilities] for more utilities.

diff --git a/src/nodes/block-tag.ts b/src/nodes/block-tag.ts
@@ -26,8 +26,8 @@ interface BlockTagData extends Data {}
  *
  * Block tags should be the only element on their line, except in cases where
  * special meaning is assigned to succeeding text. All text following a block
- * tag, up until the start of the next block tag, is considered to be the block
- * tag's **tag content**.
+ * tag name, up until the start of the next block tag name, or comment closer,
+ * is considered to be the block tag's **tag content**.
  *
  * @see {@linkcode Parent}
  * @see {@linkcode Tag}
@@ -43,7 +43,7 @@ interface BlockTag extends Parent, Tag {
    */
   children:
     | Exclude<BlockTagContent, TypeExpression>[]
-    | [TypeExpression, ...Exclude<BlockTagContent, TypeExpression>[]]
+    | [type: TypeExpression, ...Exclude<BlockTagContent, TypeExpression>[]]
 
   /**
    * Info from the ecosystem.

diff --git a/src/types/tag-name.ts b/src/types/tag-name.ts
@@ -6,8 +6,8 @@
 /**
  * A tag name.
  *
- * Tag names start with an at-sign (`@`) and may contain any ASCII letters
- * after the at-sign.
+ * Tag names start with an at-sign (`@`) and may contain any ASCII letter after
+ * the at-sign.
  *
  * @template {string} [T=string] - Tag name text
  */