Enhance VHDL emitter output for better entity/package identification#22
Merged
Conversation
…ation
- Always emit Generics section on entity pages; show '*None.*' when empty
so readers can unambiguously confirm no generics exist
- Add '*Entity declared in \{file}\*' attribution line after each entity heading
- Add '*Package declared in \{file}\*' attribution line after each package heading
- Include source filename in architecture entries formatted as
'**{name}** (\{file}\): {summary}' so readers know which file to include
- Add NoItemsPlaceholder constant to VhdlEmitter for the above
- Update design docs for VhdlEmitterGradualDisclosure and VhdlEmitterSingleFile
- Add 8 new tests covering the new behaviours across both emitters
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This pull request updates the VHDL Markdown emitters to improve traceability and consistency in generated documentation by attributing entities/packages/architectures to source filenames and standardizing empty-section output.
Changes:
- Add source file attribution paragraphs for entity and package documentation in both single-file and gradual-disclosure emitters.
- Always emit a “Generics” section for entities; when empty, emit a standardized
*None.*placeholder. - Include source filename in architecture listings (formatted as
**name** (filename): summary) and update design docs/tests accordingly.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| test/ApiMark.Vhdl.Tests/VhdlEmitterSingleFileTests.cs | Adds assertions for filename attribution and empty-generics behavior in single-file output. |
| test/ApiMark.Vhdl.Tests/VhdlEmitterGradualDisclosureTests.cs | Adds assertions for filename attribution and empty-generics behavior in gradual-disclosure output. |
| src/ApiMark.Vhdl/VhdlEmitterSingleFile.cs | Tracks per-item source filenames and emits attribution + empty-generics placeholder; augments architecture formatting with filenames. |
| src/ApiMark.Vhdl/VhdlEmitterGradualDisclosure.cs | Tracks per-item source filenames and emits attribution + empty-generics placeholder; augments architecture formatting with filenames. |
| src/ApiMark.Vhdl/VhdlEmitter.cs | Introduces NoItemsPlaceholder constant for standardized empty-section output. |
| docs/design/api-mark-vhdl/vhdl-emitter-single-file.md | Updates design documentation to reflect new attribution, placeholder, and architecture formatting. |
| docs/design/api-mark-vhdl/vhdl-emitter-gradual-disclosure.md | Updates design documentation to reflect new attribution, placeholder, and architecture formatting. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Both ArchitectureParagraphContainsFilename tests were too weak — they matched any paragraph containing the filename, which the new entity attribution line also satisfies. Updated both assertions to require both the bold architecture name and the filename in the same paragraph. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This was referenced Jun 19, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request enhances the VHDL Markdown emitters by improving the clarity and completeness of generated documentation. The main changes add explicit attribution of entities and packages to their source files, provide clearer section formatting (especially for empty sections), and improve architecture listings with file references. These updates affect both the gradual disclosure and single-file documentation emitters, as well as their design documentation.
Documentation output improvements:
Architecture listing enhancements:
**name** (filename): summary, providing more context for each architecture implementation. [1] [2]Internal code and design documentation updates:
vhdl-emitter-gradual-disclosure.mdandvhdl-emitter-single-file.md) is updated to reflect these output and API changes, including the new placeholder for empty sections and improved architecture formatting. [1] [2] [3] [4]