8000 feat(processor): append @example tags to member description body #5 by Katari-8055 · Pull Request #22 · webpack/webpack-doc-kit · GitHub
[go: up one dir, main page]
Skip to content

feat(processor): append @example tags to member description body #5#22

Closed
Katari-8055 wants to merge 7 commits intowebpack:mainfrom
Katari-8055:append-examples-to-body
Closed

feat(processor): append @example tags to member description body #5#22
Katari-8055 wants to merge 7 commits intowebpack:mainfrom
Katari-8055:append-examples-to-body

Conversation

@Katari-8055
Copy link
Contributor
@Katari-8055 Katari-8055 commented Mar 13, 2026 •
edited
Loading

Closes #5

Summary

This PR improves the visibility of code examples in the generated documentation by moving @example block tags into the main reflection body (summary). By appending these examples directly to the reflection's primary description during the processing phase, we ensure they are always rendered in the final output, even when the theme is configured to hide standard block tags. This ensures that usage examples are always accessible to developers without requiring changes to the theme's core visibility settings.

What kind of change does this PR introduce?

feat (feature for the documentation processor)

Did you add tests for your changes?

The changes were manually verified by adding a demo @example tag in webpack/types.d.ts, running npm run generate-docs, and confirming that the example appeared in the generated .md files inside the pages/v5.x directory.

Does this PR introduce a breaking change?

No.

If relevant, what needs to be documented once your changes are merged or what have you already documented?

No external documentation is required. This change automatically enhances how existing and future @example JSDoc tags are rendered in the Markdown output.

Use of AI

Yes, for research purpose !

avivkeller
avivkeller requested changes Mar 13, 2026
View reviewed changes
Copy link
Member
@avivkeller avivkeller left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This belongs in the theme, not the processor

@Katari-8055
Copy link
Contributor Author
Katari-8055 commented Mar 13, 2026

This belongs in the theme, not the processor

Thanks for the clarification! That makes sense. I'll move the implementation to the theme instead of the processor and push an update shortly.

@Katari-8055 Katari-8055 requested a review from avivkeller March 14, 2026 07:02
@avivkeller avivkeller closed this Mar 14, 2026
@Katari-8055
Copy link
Contributor Author
Katari-8055 commented Mar 14, 2026

@avivkeller

1. Bug Description

The recently merged @example tag rendering logic contains a string concatenation flaw and lacks contextual rendering support. Specifically, the renderExamples helper returns a null object when no tags are found, which JavaScript converts to the literal string "null" when used in template literals (e.g., in typedListItem). Additionally, the helper always forces a Markdown heading, which breaks the visual hierarchy when used inside property or parameter lists.

2. Expected Behavior

  • What you expected to happen
    • When no examples are present, the helper should return an empty string ("") to prevent the word "null" from appearing in the documentation.
    • The helper should support a "Hybrid" mode where it renders headings only if a headingLevel is provided, otherwise rendering just the body for inline lists.
    • Multiple examples should be distinguishably numbered (e.g., Example 1, Example 2).

3. Actual Behavior

  • What actually happened
    • Descriptions for properties/parameters are currently being appended with the literal word "null" if they lack examples (e.g., Description: some text null).
    • Forced ### Example headings are appearing inside bulleted lists, creating a cluttered and inconsistent UI.
    • The implementation lacks optional chaining for certain comment properties, which could lead to runtime crashes in edge cases.

I have implemented a fix that addresses these bugs and improves the overall documentation quality. Let me know if I should open a new PR for these improvements!

@avivkeller
Copy link
Member
avivkeller commented Mar 14, 2026

The word null is not appended. If it were, the doc-check CI would fail, and I would not have merged the PR.

Please refrain from relying solely on AI to formulate comments, it only clutters

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@avivkeller avivkeller Awaiting requested review from avivkeller

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Examples

2 participants

@Katari-8055 @avivkeller
0