docs(tags): improve writing style #3411
Conversation
- Made doc sections more consistent - Replace duplicated styling in mermaid diagram with classes - Update yaml examples to use consistent formatting and descriptions
bandantonio
requested review from
quetzalliwrites and
asyncapi-bot-eve
as code owners
WalkthroughThe pull request involves significant restructuring and rephrasing of the "Tags" document in the AsyncAPI documentation. The changes simplify definitions, clarify the roles of the Changes
Assessment against linked issues
Possibly related PRs
Suggested reviewers
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
✅ Deploy Preview for asyncapi-website ready!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify site configuration. |
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## master #3411 +/- ##
=======================================
Coverage 67.77% 67.77%
=======================================
Files 21 21
Lines 664 664
=======================================
Hits 450 450
Misses 214 214 ☔ View full report in Codecov by Sentry. 🚨 Try these New Features:
|
|
⚡️ Lighthouse report for the changes in this PR:
Lighthouse ran on https://deploy-preview-3411--asyncapi-website.netlify.app/ |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (4)
markdown/docs/concepts/asyncapi-document/tags.md (4)
14-14: Consider using "brief" instead of "short".To strengthen the writing style, consider replacing "short" with "brief" in the description property definition.
-- `description`: A short description explaining the tag's purpose or usage. ++ `description`: A brief description explaining the tag's purpose or usage.🧰 Tools
🪛 LanguageTool
[uncategorized] ~14-~14: Loose punctuation mark.
Context: ...e: The name of the tag. -description`: A short description explaining the tag'...(UNLIKELY_OPENING_PUNCTUATION)
[style] ~14-~14: Consider using the synonym “brief” (= concise, using a few words, not lasting long) to strengthen your wording.
Context: ...The name of the tag. -description: A short description explaining the tag's purpos...(QUICK_BRIEF)
66-67: Improve bullet point consistency.The bullet points have inconsistent formatting. Consider making them parallel in structure.
-- criteria like location, environment type (like production or development), and unique server features. -- specific tags or labels. ++ Location, environment type (production/development), and unique server features ++ Specific tags and labels for server identification
Line range hint
239-254: Fix YAML indentation.The YAML example needs consistent indentation for better readability.
-name: SimpleSignup -summary: A simple UserSignup example message -tags: - - name: userSignUp - description: some message related to user signup -headers: - correlationId: my-correlation-id - applicationInstanceId: myInstanceId -payload: - user: - someUserKey: someUserValue - signup: - someSignupKey: someSignupValue +name: SimpleSignup +summary: A simple UserSignup example message +tags: + - name: userSignUp + description: some message related to user signup +headers: + correlationId: my-correlation-id + applicationInstanceId: myInstanceId +payload: + user: + someUserKey: someUserValue + signup: + someSignupKey: someSignupValue
338-338: Remove unused link reference.The link reference
[components-field]is not used in the document.-[components-field]: /docs/concepts/asyncapi-document/structure#components-field🧰 Tools
🪛 Markdownlint
338-338: Unused link or image reference definition: "components-field"
Link and image reference definitions should be needed(MD053, link-image-reference-definitions)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (1)
markdown/docs/concepts/asyncapi-document/tags.md(14 hunks)
🧰 Additional context used
🪛 LanguageTool
markdown/docs/concepts/asyncapi-document/tags.md
[uncategorized] ~13-~13: Loose punctuation mark.
Context: ...ains the following properties: - name: The name of the tag. - description: A...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~14-~14: Loose punctuation mark.
Context: ...e: The name of the tag. - description`: A short description explaining the tag'...
(UNLIKELY_OPENING_PUNCTUATION)
[style] ~14-~14: Consider using the synonym “brief” (= concise, using a few words, not lasting long) to strengthen your wording.
Context: ...The name of the tag. - description: A short description explaining the tag's purpos...
(QUICK_BRIEF)
[uncategorized] ~15-~15: Loose punctuation mark.
Context: ...tag's purpose or usage. - externalDocs: Additional external documentation for t...
(UNLIKELY_OPENING_PUNCTUATION)
🪛 Markdownlint
markdown/docs/concepts/asyncapi-document/tags.md
338-338: Unused link or image reference definition: "components-field"
Link and image reference definitions should be needed
(MD053, link-image-reference-definitions)
🔇 Additional comments (3)
markdown/docs/concepts/asyncapi-document/tags.md (3)
Line range hint 22-60: LGTM! Clear explanation with consistent styling.
The section effectively explains tags in the info object context, with well-structured visual representation and practical examples.
Line range hint 116-164: LGTM! Well-structured explanation with clear examples.
The section effectively explains channel tags with appropriate visual aids and examples.
Line range hint 165-216: LGTM! Comprehensive coverage of operations tags.
The section provides a thorough explanation with well-structured examples and diagrams.
Description
Related issue(s)
Fixes #3410
See also #3375
Summary by CodeRabbit
tagsobject and its properties.tagsat theinfolevel to clarify their categorization role.