feat(types)!: TagName

Signed-off-by: Lexus Drumgold <[email protected]>

README.md

@@ -157,7 +157,7 @@ Its content is limited to [**comment**](#comment) nodes and [docast content](#co
 interface BlockTag extends Parent, Tag {
  children: BlockTagContent[]
  data?: BlockTagData | undefined
- type: 'block-tag'
+ type: 'blockTag'
 }
 ```
 
@@ -226,7 +226,7 @@ a comment, before any [**block tags**](#blocktag), and may contain [Markdown][md
 ```ts
 interface InlineTag extends Literal, Tag {
  data?: InlineTagData | undefined
- type: 'inline-tag'
+ type: 'inlineTag'
 }
 ```
 
@@ -256,7 +256,7 @@ contain [**comment**](#comment) nodes.
 ```ts
 interface TypeExpression extends Literal {
  data?: TypeExpressionData | undefined
- type: 'type-expression'
+ type: 'typeExpression'
 }
 ```
 
@@ -271,19 +271,14 @@ interface TypeExpression extends Literal {
 
 ```ts
 interface Tag {
- name: string
- prefix: string
- tag: string
+ name: TagName
 }
 ```
 
 **Tag** represents metadata associated with a [**comment**](#comment).
 
-The `prefix` field represents the tag prefix. The value is a non-empty string.
-
-The `name` field represents the tag name without `prefix`. The value of the `name` field is a non-empty string.
-
-The `tag` field represents the parsed tag. The value of `tag` field is `prefix` and `name`.
+The `name` field represents the tag name. Tag names start with an at-sign (`@`) and may contain any ASCII letters after
+the at-sign.
 
 ## Content model
 

src/mixins/__tests__/tag.spec-d.ts

@@ -3,14 +3,11 @@
  * @module docast/mixins/tests/unit-d/Tag
  */
 
+import type { TagName } from '@flex-development/docast'
 import type TestSubject from '../tag'
 
 describe('unit-d:mixins/Tag', () => {
- it('should match [name: string]', () => {
- expectTypeOf<TestSubject>().toHaveProperty('name').toBeString()
- })
-
- it('should match [tag: string]', () => {
- expectTypeOf<TestSubject>().toHaveProperty('tag').toBeString()
+ it('should match [name: TagName]', () => {
+ expectTypeOf<TestSubject>().toHaveProperty('name').toEqualTypeOf<TagName>()
  })
 })

src/mixins/tag.ts

@@ -3,19 +3,20 @@
  * @module docast/mixins/Tag
  */
 
+import type { TagName } from '@flex-development/docast'
+
 /**
- * Metadata associated with a docblock comment.
+ * Comment metadata.
+ *
+ * docast distinguishes between two kinds of tags: **block** and **inline**.
  */
 interface Tag {
  /**
  * Tag name.
+ *
+ * @see {@linkcode TagName}
  */
- name: string
-
- /**
- * Parsed tag.
- */
- tag: string
+ name: TagName
 }
 
 export type { Tag as default }

src/nodes/__tests__/block-tag.spec-d.ts

@@ -3,48 +3,51 @@
  * @module docast/nodes/tests/unit-d/BlockTag
  */
 
-import type { BlockTagContent } from '#src/content'
-import type { Tag } from '#src/mixins'
+import type {
+ BlockTagContent,
+ Data,
+ Parent,
+ Tag,
+ TypeExpression
+} from '@flex-development/docast'
 import type { Optional } from '@flex-development/tutils'
-import type { BlockTagData, default as TestSubject } from '../block-tag'
-import type Parent from '../parent'
-import type TypeExpression from '../type-expression'
+import type * as TestSubject from '../block-tag'
 
 describe('unit-d:nodes/BlockTag', () => {
+ type Subject = TestSubject.default
+ type SubjectData = TestSubject.BlockTagData
+
  it('should extend Parent', () => {
- expectTypeOf<TestSubject>().toMatchTypeOf<Parent>()
+ expectTypeOf<Subject>().toMatchTypeOf<Parent>()
  })
 
  it('should extend Tag', () => {
- expectTypeOf<TestSubject>().toMatchTypeOf<Tag>()
+ expectTypeOf<Subject>().toMatchTypeOf<Tag>()
  })
 
- it('should match [children: Exclude<BlockTagContent, TypeExpression>[]]', () => {
- expectTypeOf<TestSubject>()
- .toHaveProperty('children')
- .extract<Exclude<BlockTagContent, TypeExpression>[]>()
- .toBeArray()
- })
+ it('should match [children: Exclude<BlockTagContent, TypeExpression>[] | [TypeExpression, ...Exclude<BlockTagContent, TypeExpression>[]]]', () => {
+ // Arrange
+ type Expect =
+ | Exclude<BlockTagContent, TypeExpression>[]
+ | [TypeExpression, ...Exclude<BlockTagContent, TypeExpression>[]]
 
- it('should match [children: [TypeExpression, ...Exclude<BlockTagContent, TypeExpression>[]]]', () => {
- expectTypeOf<TestSubject>()
- .toHaveProperty('children')
- .extract<[
- TypeExpression,
- ...Exclude<BlockTagContent, TypeExpression>[]
- ]>()
- .toBeArray()
+ // Expect
+ expectTypeOf<Subject>().toHaveProperty('children').toEqualTypeOf<Expect>()
  })
 
  it('should match [data?: Optional<BlockTagData>]', () => {
- expectTypeOf<TestSubject>()
+ expectTypeOf<Subject>()
  .toHaveProperty('data')
- .toEqualTypeOf<Optional<BlockTagData>>()
+ .toEqualTypeOf<Optional<SubjectData>>()
  })
 
  it('should match [type: "blockTag"]', () => {
- expectTypeOf<TestSubject>()
- .toHaveProperty('type')
- .toEqualTypeOf<'blockTag'>()
+ expectTypeOf<Subject>().toHaveProperty('type').toEqualTypeOf<'blockTag'>()
+ })
+
+ describe('BlockTagData', () => {
+ it('should extend Data', () => {
+ expectTypeOf<SubjectData>().toMatchTypeOf<Data>()
+ })
  })
 })

src/nodes/__tests__/inline-tag.spec-d.ts

@@ -3,29 +3,35 @@
  * @module docast/nodes/tests/unit-d/InlineTag
  */
 
-import type { Tag } from '#src/mixins'
+import type { Data, Literal, Tag } from '@flex-development/docast'
 import type { Optional } from '@flex-development/tutils'
-import type { InlineTagData, default as TestSubject } from '../inline-tag'
-import type Literal from '../literal'
+import type * as TestSubject from '../inline-tag'
 
 describe('unit-d:nodes/InlineTag', () => {
+ type Subject = TestSubject.default
+ type SubjectData = TestSubject.InlineTagData
+
  it('should extend Literal', () => {
- expectTypeOf<TestSubject>().toMatchTypeOf<Literal>()
+ expectTypeOf<Subject>().toMatchTypeOf<Literal>()
  })
 
  it('should extend Tag', () => {
- expectTypeOf<TestSubject>().toMatchTypeOf<Tag>()
+ expectTypeOf<Subject>().toMatchTypeOf<Tag>()
  })
 
  it('should match [data?: Optional<InlineTagData>]', () => {
- expectTypeOf<TestSubject>()
+ expectTypeOf<Subject>()
  .toHaveProperty('data')
- .toEqualTypeOf<Optional<InlineTagData>>()
+ .toEqualTypeOf<Optional<SubjectData>>()
  })
 
  it('should match [type: "inlineTag"]', () => {
- expectTypeOf<TestSubject>()
- .toHaveProperty('type')
- .toEqualTypeOf<'inlineTag'>()
+ expectTypeOf<Subject>().toHaveProperty('type').toEqualTypeOf<'inlineTag'>()
+ })
+
+ describe('InlineTagData', () => {
+ it('should extend Data', () => {
+ expectTypeOf<SubjectData>().toMatchTypeOf<Data>()
+ })
  })
 })

src/nodes/__tests__/literal.spec-d.ts

@@ -3,8 +3,8 @@
  * @module docast/nodes/tests/unit-d/Literal
  */
 
+import type { Node } from '@flex-development/docast'
 import type TestSubject from '../literal'
-import type Node from '../node'
 
 describe('unit-d:nodes/Literal', () => {
  it('should extend Node', () => {

src/nodes/__tests__/type-expression.spec-d.ts

@@ -3,27 +3,33 @@
  * @module docast/nodes/tests/unit-d/TypeExpression
  */
 
+import type { Data, Literal } from '@flex-development/docast'
 import type { Optional } from '@flex-development/tutils'
-import type Literal from '../literal'
-import type {
- default as TestSubject,
- TypeExpressionData
-} from '../type-expression'
+import type * as TestSubject from '../type-expression'
 
 describe('unit-d:nodes/TypeExpression', () => {
+ type Subject = TestSubject.default
+ type SubjectData = TestSubject.TypeExpressionData
+
  it('should extend Literal', () => {
- expectTypeOf<TestSubject>().toMatchTypeOf<Literal>()
+ expectTypeOf<Subject>().toMatchTypeOf<Literal>()
  })
 
  it('should match [data?: Optional<TypeExpressionData>]', () => {
- expectTypeOf<TestSubject>()
+ expectTypeOf<Subject>()
  .toHaveProperty('data')
- .toEqualTypeOf<Optional<TypeExpressionData>>()
+ .toEqualTypeOf<Optional<SubjectData>>()
  })
 
  it('should match [type: "typeExpression"]', () => {
- expectTypeOf<TestSubject>()
+ expectTypeOf<Subject>()
  .toHaveProperty('type')
  .toEqualTypeOf<'typeExpression'>()
  })
+
+ describe('TypeExpressionData', () => {
+ it('should extend Data', () => {
+ expectTypeOf<SubjectData>().toMatchTypeOf<Data>()
+ })
+ })
 })

src/nodes/block-tag.ts

@@ -3,15 +3,17 @@
  * @module docast/nodes/BlockTag
  */
 
-import type { BlockTagContent } from '#src/content'
-import type { Data } from '#src/interfaces'
-import type { Tag } from '#src/mixins'
+import type {
+ BlockTagContent,
+ Data,
+ Parent,
+ Tag,
+ TypeExpression
+} from '@flex-development/docast'
 import type { Optional } from '@flex-development/tutils'
-import type Parent from './parent'
-import type TypeExpression from './type-expression'
 
 /**
- * Info associated with block tag nodes.
+ * Info associated with block tags.
  *
  * @see {@linkcode Data}
  *
@@ -22,6 +24,11 @@ interface BlockTagData extends Data {}
 /**
  * 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, up until the start of the next block tag, is considered to be the block
+ * tag's **tag content**.
+ *
  * @see {@linkcode Parent}
  * @see {@linkcode Tag}
  *
@@ -39,7 +46,7 @@ interface BlockTag extends Parent, Tag {
  | [TypeExpression, ...Exclude<BlockTagContent, TypeExpression>[]]
 
  /**
- * Data associated with block tag.
+ * Info from the ecosystem.
  *
  * @see {@linkcode BlockTagData}
  */

src/nodes/inline-tag.ts

@@ -3,13 +3,11 @@
  * @module docast/nodes/InlineTag
  */
 
-import type { Data } from '#src/interfaces'
-import type { Tag } from '#src/mixins'
+import type { Data, Literal, Tag } from '@flex-development/docast'
 import type { Optional } from '@flex-development/tutils'
-import type Literal from './literal'
 
 /**
- * Info associated with inline tag nodes.
+ * Info associated with inline tags.
  *
  * @see {@linkcode Data}
  *
@@ -20,14 +18,18 @@ interface InlineTagData extends Data {}
 /**
  * Inline metadata.
  *
+ * Inline tags are denoted by wrapping a tag name and any **tag content** in
+ * angle brackets (`{` and `}`).
+ *
+ * @see {@linkcode Literal}
  * @see {@linkcode Tag}
  *
  * @extends {Literal}
  * @extends {Tag}
  */
 interface InlineTag extends Literal, Tag {
  /**
- * Data associated with inline tag.
+ * Info from the ecosystem.
  *
  * @see {@linkcode InlineTagData}
  */

src/nodes/literal.ts

@@ -3,7 +3,7 @@
  * @module docast/nodes/Literal
  */
 
-import type Node from './node'
+import type { Node } from '@flex-development/docast'
 
 /**
  * Abstract docast node containing the smallest possible value.

src/nodes/type-expression.ts

@@ -3,12 +3,11 @@
  * @module docast/nodes/TypeExpression
  */
 
-import type { Data } from '#src/interfaces'
+import type { Data, Literal } from '@flex-development/docast'
 import type { Optional } from '@flex-development/tutils'
-import type Literal from './literal'
 
 /**
- * Info associated with type expression nodes.
+ * Info associated with type expressions.
  *
  * @see {@linkcode Data}
  *
@@ -17,15 +16,15 @@ import type Literal from './literal'
 interface TypeExpressionData extends Data {}
 
 /**
- * A type definition or constraint.
+ * A type definition or constraint denoted in block tag **tag content**.
  *
  * @see {@linkcode Literal}
  *
  * @extends {Literal}
  */
 interface TypeExpression extends Literal {
  /**
- * Data associated with type expression.
+ * Info from the ecosystem.
  *
  * @see {@linkcode TypeExpressionData}
  */