refactor(nodes)!: Comment#children

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

src/interfaces/__tests__/code-segment.spec-d.ts

@@ -3,9 +3,9 @@
  * @module docast/interfaces/tests/unit-d/CodeSegment
  */
 
+import type { Position } from '@flex-development/docast'
 import type { Nilable, NumberString } from '@flex-development/tutils'
 import type TestSubject from '../code-segment'
-import type Position from '../position'
 
 describe('unit-d:interfaces/CodeSegment', () => {
  it('should match [identifier: string]', () => {

src/interfaces/code-segment.ts

@@ -3,8 +3,8 @@
  * @module docast/interfaces/CodeSegment
  */
 
+import type { Position } from '@flex-development/docast'
 import type { Nilable, NumberString } from '@flex-development/tutils'
-import type Position from './position'
 
 /**
  * The segment of code a comment documents.

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

@@ -3,38 +3,53 @@
  * @module docast/nodes/tests/unit-d/Comment
  */
 
-import type { FlowContent } from '#src/content'
-import type { CodeSegment } from '#src/interfaces'
+import type {
+ CodeSegment,
+ Data,
+ Description,
+ FlowContent,
+ Parent
+} from '@flex-development/docast'
 import type { Nilable, Optional } from '@flex-development/tutils'
-import type { CommentData, default as TestSubject } from '../comment'
-import type Parent from '../parent'
+import type * as TestSubject from '../comment'
 
 describe('unit-d:nodes/Comment', () => {
+ type Subject = TestSubject.default
+ type SubjectData = TestSubject.CommentData
+
  it('should extend Parent', () => {
- expectTypeOf<TestSubject>().toMatchTypeOf<Parent>()
+ expectTypeOf<Subject>().toMatchTypeOf<Parent>()
  })
 
- it('should match [children: FlowContent[]]', () => {
- expectTypeOf<TestSubject>()
- .toHaveProperty('children')
- .toEqualTypeOf<FlowContent[]>()
+ it('should match [children: Exclude<FlowContent, Description>[] | [Description, ...Exclude<FlowContent, Description>[]]]', () => {
+ // Arrange
+ type Expect =
+ | Exclude<FlowContent, Description>[]
+ | [summary: Description, ...Exclude<FlowContent, Description>[]]
+
+ // Expect
+ expectTypeOf<Subject>().toHaveProperty('children').toEqualTypeOf<Expect>()
  })
 
  it('should match [code?: Nilable<CodeSegment>]', () => {
- expectTypeOf<TestSubject>()
+ expectTypeOf<Subject>()
  .toHaveProperty('code')
  .toEqualTypeOf<Nilable<CodeSegment>>()
  })
 
  it('should match [data?: Optional<CommentData>]', () => {
- expectTypeOf<TestSubject>()
+ expectTypeOf<Subject>()
  .toHaveProperty('data')
- .toEqualTypeOf<Optional<CommentData>>()
+ .toEqualTypeOf<Optional<SubjectData>>()
  })
 
  it('should match [type: "comment"]', () => {
- expectTypeOf<TestSubject>()
- .toHaveProperty('type')
- .toEqualTypeOf<'comment'>()
+ expectTypeOf<Subject>().toHaveProperty('type').toEqualTypeOf<'comment'>()
+ })
+
+ describe('CommentData', () => {
+ it('should extend Data', () => {
+ expectTypeOf<SubjectData>().toMatchTypeOf<Data>()
+ })
  })
 })

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

@@ -3,31 +3,43 @@
  * @module docast/nodes/tests/unit-d/Description
  */
 
-import type { DescriptionContent } from '#src/content'
+import type {
+ Data,
+ DescriptionContent,
+ Parent
+} from '@flex-development/docast'
 import type { Optional } from '@flex-development/tutils'
-import type { DescriptionData, default as TestSubject } from '../description'
-import type Parent from '../parent'
+import type * as TestSubject from '../description'
 
 describe('unit-d:nodes/Description', () => {
+ type Subject = TestSubject.default
+ type SubjectData = TestSubject.DescriptionData
+
  it('should extend Parent', () => {
- expectTypeOf<TestSubject>().toMatchTypeOf<Parent>()
+ expectTypeOf<Subject>().toMatchTypeOf<Parent>()
  })
 
  it('should match [children: DescriptionContent[]]', () => {
- expectTypeOf<TestSubject>()
+ expectTypeOf<Subject>()
  .toHaveProperty('children')
  .toEqualTypeOf<DescriptionContent[]>()
  })
 
  it('should match [data?: Optional<DescriptionData>]', () => {
- expectTypeOf<TestSubject>()
+ expectTypeOf<Subject>()
  .toHaveProperty('data')
- .toEqualTypeOf<Optional<DescriptionData>>()
+ .toEqualTypeOf<Optional<SubjectData>>()
  })
 
  it('should match [type: "description"]', () => {
- expectTypeOf<TestSubject>()
+ expectTypeOf<Subject>()
  .toHaveProperty('type')
  .toEqualTypeOf<'description'>()
  })
+
+ describe('DescriptionData', () => {
+ it('should extend Data', () => {
+ expectTypeOf<SubjectData>().toMatchTypeOf<Data>()
+ })
+ })
 })

src/nodes/comment.ts

@@ -3,13 +3,17 @@
  * @module docast/nodes/Comment
  */
 
-import type { FlowContent } from '#src/content'
-import type { CodeSegment, Data } from '#src/interfaces'
+import type {
+ CodeSegment,
+ Data,
+ Description,
+ FlowContent,
+ Parent
+} from '@flex-development/docast'
 import type { Nilable, Optional } from '@flex-development/tutils'
-import type Parent from './parent'
 
 /**
- * Info associated with comment nodes.
+ * Info associated with comments.
  *
  * @see {@linkcode Data}
  *
@@ -32,9 +36,12 @@ interface Comment extends Parent {
  /**
  * List of children.
  *
+ * @see {@linkcode Description}
  * @see {@linkcode FlowContent}
  */
- children: FlowContent[]
+ children:
+ | Exclude<FlowContent, Description>[]
+ | [summary: Description, ...Exclude<FlowContent, Description>[]]
 
  /**
  * Code segment documented by comment.
@@ -44,7 +51,7 @@ interface Comment extends Parent {
  code?: Nilable<CodeSegment>
 
  /**
- * Data associated with comment.
+ * Info from the ecosystem.
  *
  * @see {@linkcode CommentData}
  */

src/nodes/description.ts

@@ -3,13 +3,15 @@
  * @module docast/nodes/Description
  */
 
-import type { DescriptionContent } from '#src/content'
-import type { Data } from '#src/interfaces'
+import type {
+ Data,
+ DescriptionContent,
+ Parent
+} from '@flex-development/docast'
 import type { Optional } from '@flex-development/tutils'
-import type Parent from './parent'
 
 /**
- * Info associated with implicit description nodes.
+ * Info associated with comment descriptions.
  *
  * @see {@linkcode Data}
  *
@@ -18,7 +20,7 @@ import type Parent from './parent'
 interface DescriptionData extends Data {}
 
 /**
- * A piece of text located at the **beginning** of a docblock comment.
+ * Text located at the **beginning** of a comment, before any block tags.
  *
  * @see {@linkcode Parent}
  *
@@ -33,7 +35,7 @@ interface Description extends Parent {
  children: DescriptionContent[]
 
  /**
- * Data associated with implicit description.
+ * Info from the ecosystem.
  *
  * @see {@linkcode DescriptionData}
  */