docs: introduce and use more categories in JSDoc #807
Conversation
Attach more elements to specific categories to better group them in the HTML API documentation Add new categories: - Animation - Change - Event - Geometry - Serialization - Shape - Utils Reduce the number of typedoc warnings. Also improve the JSDoc in various places.
WalkthroughThis set of changes focuses on improving and standardizing the documentation across various files in the codebase, primarily through the addition and refinement of JSDoc comments and category annotations. Categories such as "Animation," "Change," "Event," "Geometry," "Serialization," "Shape," "Style," "Utils," "GUI," "Navigation," and "Configuration" are introduced or reorganized to better group and clarify the purpose of classes, types, and exports for documentation generation. Example code snippets in documentation are modernized for clarity and consistency. No functional, logical, or structural code changes are made; all updates are limited to documentation and metadata. Changes
Sequence Diagram(s)No sequence diagrams are generated since all changes are documentation-only and do not affect control flow or introduce new features. Possibly related PRs
📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (2)
✅ Files skipped from review due to trivial changes (1)
🚧 Files skipped from review as they are similar to previous changes (1)
✨ Finishing Touches
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. 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 (
|
![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
🧹 Nitpick comments (5)
packages/core/src/view/canvas/XmlCanvas2D.ts (1)
25-27: Add a brief summary above@categoryfor consistency.The new JSDoc block only declares the category without any description. For better documentation (and to match other classes such as
ImageExport), prepend a one-line summary. For example:/** * XML canvas implementation for serializing drawing commands. * @category Serialization */packages/core/src/view/geometry/Point.ts (1)
25-27: Consider adding@paramtags to the constructor.Although the constructor has a description, explicit
@paramannotations improve clarity:/** * Constructs a new point for the optional x and y coordinates. * * @param x - The x-coordinate (default is 0). * @param y - The y-coordinate (default is 0). */packages/core/src/editor/EditorToolbar.ts (2)
86-87: Remove duplicated default info from description or adjust @default usage.The description already mentions “Default is 4 (40 pixels).” and there’s a
@default 4tag. You may want to either:
- Remove the “Default is 4 (40 pixels).” from the description, or
- Clarify units in the tag (e.g.,
@default 4vs.@default 40px) for consistency.- * Defines the spacing ... Default is 4 (40 pixels). - * - * @default 4 + * Defines the spacing between existing and new vertices in gridSize units when dropped. + * + * @default 4
93-93: Remove trailing period in@defaulttag.Standard JSDoc syntax for
@defaultvalues avoids trailing punctuation:- * @default false. + * @default falsepackages/core/src/view/other/Outline.ts (1)
197-197: Document thesizerpropertyThere is a
// TODO: Document me!!comment above thesizerproperty. Please add a JSDoc comment describing its purpose and usage.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (38)
packages/core/src/Client.ts(1 hunks)packages/core/src/editor/EditorToolbar.ts(1 hunks)packages/core/src/index.ts(3 hunks)packages/core/src/types.ts(7 hunks)packages/core/src/view/animate/Animation.ts(1 hunks)packages/core/src/view/animate/Effects.ts(1 hunks)packages/core/src/view/animate/Morphing.ts(1 hunks)packages/core/src/view/canvas/XmlCanvas2D.ts(1 hunks)packages/core/src/view/cell/CellStatePreview.ts(0 hunks)packages/core/src/view/event/EventObject.ts(1 hunks)packages/core/src/view/event/EventSource.ts(1 hunks)packages/core/src/view/event/InternalEvent.ts(1 hunks)packages/core/src/view/event/InternalMouseEvent.ts(1 hunks)packages/core/src/view/geometry/Geometry.ts(1 hunks)packages/core/src/view/geometry/Point.ts(1 hunks)packages/core/src/view/geometry/Rectangle.ts(1 hunks)packages/core/src/view/geometry/Shape.ts(1 hunks)packages/core/src/view/geometry/stencil/StencilShape.ts(2 hunks)packages/core/src/view/geometry/stencil/StencilShapeRegistry.ts(1 hunks)packages/core/src/view/image/ImageExport.ts(1 hunks)packages/core/src/view/layout/PartitionLayout.ts(1 hunks)packages/core/src/view/other/Outline.ts(1 hunks)packages/core/src/view/other/PanningManager.ts(1 hunks)packages/core/src/view/plugins/PanningHandler.ts(1 hunks)packages/core/src/view/style/marker/EdgeMarkerRegistry.ts(1 hunks)packages/core/src/view/undoable_changes/CellAttributeChange.ts(1 hunks)packages/core/src/view/undoable_changes/ChildChange.ts(1 hunks)packages/core/src/view/undoable_changes/CollapseChange.ts(1 hunks)packages/core/src/view/undoable_changes/CurrentRootChange.ts(1 hunks)packages/core/src/view/undoable_changes/GeometryChange.ts(1 hunks)packages/core/src/view/undoable_changes/RootChange.ts(1 hunks)packages/core/src/view/undoable_changes/SelectionChange.ts(1 hunks)packages/core/src/view/undoable_changes/StyleChange.ts(1 hunks)packages/core/src/view/undoable_changes/TerminalChange.ts(1 hunks)packages/core/src/view/undoable_changes/UndoableEdit.ts(1 hunks)packages/core/src/view/undoable_changes/ValueChange.ts(1 hunks)packages/core/src/view/undoable_changes/VisibleChange.ts(1 hunks)packages/core/tsconfig.json(2 hunks)
💤 Files with no reviewable changes (1)
- packages/core/src/view/cell/CellStatePreview.ts
🧰 Additional context used
🧬 Code Graph Analysis (1)
packages/core/src/view/undoable_changes/CellAttributeChange.ts (2)
packages/core/src/types.ts (1)
UndoableChange(38-42)packages/core/src/view/cell/Cell.ts (1)
Cell(66-892)
⏰ Context from checks skipped due to timeout of 90000ms (3)
- GitHub Check: build (macos-14)
- GitHub Check: build (windows-2022)
- GitHub Check: build
🔇 Additional comments (48)
packages/core/src/view/geometry/Geometry.ts (1)
82-84: Add@category Geometrytag
The new@category GeometryJSDoc annotation correctly classifies this class in the Geometry section of the generated documentation, improving organization and discoverability.packages/core/src/view/undoable_changes/CurrentRootChange.ts (1)
26-28: Add@category Changetag
Including the@category Changeannotation aligns this undoable change class with the PR’s documentation categorization scheme, grouping it under Change actions.packages/core/src/view/undoable_changes/StyleChange.ts (1)
25-26: Replace class tag with@category Change
Switching from the old@classtag to@category Changestandardizes this class with other undoable changes and improves consistency.packages/core/src/view/event/InternalEvent.ts (1)
66-68: Add@category Eventtag
The newly added@category Eventannotation properly categorizes this internal event helper class for documentation, matching similar event-related entities.packages/core/src/view/geometry/stencil/StencilShapeRegistry.ts (1)
44-47: Add@category Configurationand@category Shapetags
Adding both@category Configurationand@category Shapeannotations ensures this registry is discoverable under configuration utilities and shape-related docs, following the PR’s dual-categorization pattern.packages/core/src/view/style/marker/EdgeMarkerRegistry.ts (1)
32-34: Consistent JSDoc category annotations applied
The new@category Configurationand@category Styletags align with the project's documentation conventions and improve API organization.packages/core/src/view/image/ImageExport.ts (1)
47-48: Added@category SerializationJSDoc tag
CategorizingImageExportunder "Serialization" enhances documentation clarity and aligns with other serialization classes.packages/core/src/view/undoable_changes/UndoableEdit.ts (1)
60-60: Fixed typographical error in JSDoc comment
Corrected "changeswas" to "changes was" for improved readability.packages/core/src/Client.ts (1)
21-23: Added@category ConfigurationtoClient
This categorization improves documentation organization for theClientclass.packages/core/src/view/undoable_changes/RootChange.ts (1)
25-26: Simplified class-level JSDoc with@category Change
Streamlines documentation and alignsRootChangewith other undoable change classes.packages/core/src/view/undoable_changes/ValueChange.ts (1)
25-26: Category tag placement is correct.The JSDoc has a concise description and the
@category Changetag is in the right position. No further changes needed.packages/core/src/view/undoable_changes/VisibleChange.ts (1)
25-26: Category tag placement is correct.The JSDoc has a concise class description and the
@category Changetag is properly added. Looks good.packages/core/src/view/geometry/Point.ts (1)
22-23: Category tag placement is correct.The
@category Geometrytag is added right after the class description, matching the project’s convention. No changes required here.packages/core/src/view/geometry/Rectangle.ts (2)
21-25: Add Geometry category to Rectangle JSDoc
The new@category Geometrytag correctly groups this class under the Geometry section in the generated docs.
27-29: Simplify constructor JSDoc
The concise constructor description aligns with the PR’s goal of streamlined, accurate documentation.packages/core/src/view/layout/PartitionLayout.ts (2)
68-71: Annotate default forresizeVertices
Replacing the inline default text with@default truestandardizes default-value documentation across the codebase.
73-76: Use inline link inisHorizontal()JSDoc
Linking directly to thehorizontalproperty improves clarity and navigability in the docs.packages/core/src/view/other/PanningManager.ts (1)
26-29: Add Navigation category to PanningManager
The@category Navigationtag consistently groups panning-related classes under navigation in the API docs.packages/core/src/view/animate/Animation.ts (1)
24-27: Add Animation category to Animation class
Including@category Animationensures this class appears in the Animation section of the documentation.packages/core/src/view/undoable_changes/SelectionChange.ts (1)
24-28: Add Change category to SelectionChange JSDoc
The@category Changetag correctly categorizes this undoable change under Change operations in the docs.packages/core/src/view/undoable_changes/TerminalChange.ts (1)
24-26: Consistent JSDoc categorization added
The@category Changetag is correctly inserted into the class-level JSDoc, aligning this change class with others in the module.packages/core/src/view/undoable_changes/GeometryChange.ts (1)
26-26: Consistent JSDoc categorization added
The@category Changetag is properly added to categorize this geometry change class alongside its counterparts.packages/core/src/view/animate/Effects.ts (1)
33-35: Consistent JSDoc categorization added
The@category Animationtag has been correctly applied to theEffectsclass JSDoc, grouping it with other animation-related APIs.packages/core/src/view/undoable_changes/CollapseChange.ts (1)
25-26: Consistent JSDoc categorization added
The@category Changeannotation is now present, standardizing the documentation of this collapse change class with the rest of the module.packages/core/src/view/plugins/PanningHandler.ts (1)
60-62: Additional JSDoc categorization added
The@category Navigationtag complements the existing@category Plugin, making the handler appear under both plugin and navigation sections as intended.packages/core/src/view/event/EventSource.ts (1)
46-46: Appropriate categorization under "Event".The addition of
@category Eventcorrectly classifies theEventSourceclass for documentation grouping and aligns it with other event-related entities.packages/core/src/view/geometry/Shape.ts (1)
86-87: Correct category assigned for Shape.The
@category Shapetag accurately groups theShapeclass under the Shape category. Its placement immediately after the description and before the class declaration is consistent with the project's JSDoc conventions.packages/core/src/view/geometry/stencil/StencilShape.ts (2)
35-36: Dual categorization for configuration and shapes.The
StencilShapeConfigexport is now tagged with both@category Configurationand@category Shape. If the goal is to list this configuration object under both categories in the generated docs, this is correct—but please verify that Typedoc supports multiple@categoryentries on a single symbol.
65-66: CategorizeStencilShapecorrectly.Adding
@category Shapeto theStencilShapeclass aligns it with other geometry entities and improves discoverability. The tag placement is consistent with the surrounding JSDoc blocks.packages/core/src/view/undoable_changes/ChildChange.ts (1)
25-25: Consistent change grouping.Tagging
ChildChangewith@category Changecorrectly groups it alongside other undoable change classes, streamlining the documentation and matching the style of sibling files.packages/core/src/view/event/InternalMouseEvent.ts (2)
52-52: Correct category tag for internal mouse events.Adding
@category EventtoInternalMouseEventaligns it with other event classes and ensures consistent grouping in the API documentation.
55-60: Constructor documentation enhanced.The newly introduced JSDoc comment for the constructor uses
@paramannotations with a{@link CellState}reference, clearly describes default values, and follows the project's formatting conventions.packages/core/tsconfig.json (1)
23-47: Verify updated category order meets documentation needsThe new
categoryOrderarray has been expanded with the added categories (Animation,Change,Event,Geometry,Serialization,Shape,Utils) in the intended positions. This aligns with the newly annotated JSDoc tags across the codebase and should reduce Typedoc warnings.packages/core/src/view/event/EventObject.ts (1)
21-32: Approve enhanced JSDoc and category annotationThe class-level documentation has been clarified (renaming
mxEventObject→EventObject), usage examples are well formatted, and the@category Eventtag correctly groups this class.packages/core/src/view/undoable_changes/CellAttributeChange.ts (1)
21-42: Approve revised documentation and category taggingThe JSDoc has been streamlined with modern code examples (
const), the wording is concise, and the@category Changetag correctly categorizes this undoable change action.packages/core/src/view/animate/Morphing.ts (2)
26-47: Approve class-level JSDoc improvementsThe top-level comment now clearly describes the
Morphingclass, includes a working example withconst, and adds the@category Animationtag in line with other animation components.
49-56: Approve constructor JSDoc enhancementsThe constructor’s JSDoc now documents all parameters with default values (
steps = 6,ease = 1.5, optionaldelay) and clarifies their roles.packages/core/src/view/other/Outline.ts (1)
42-71: Approve Outline class documentation and categorizationThe class JSDoc has been modernized with clear descriptions, updated examples using
const, and the@category Navigationtag added for improved grouping in the navigation section of the API docs.packages/core/src/index.ts (4)
133-144: Consistent@category Utilsfor pure utility exports
The addition of@category UtilsJSDoc tags to these exports (cellArrayUtils, cloneUtils, constants, domUtils, gestureUtils, mathUtils, printUtils, stringUtils, styleUtils, xmlUtils, requestUtils) aligns with the updated TypeDoc configuration and improves discoverability of core utilities.Also applies to: 150-153, 159-162, 163-166, 167-170, 171-174, 175-178, 179-182, 234-237
145-149: Dual categories forDomHelpers: GUI & Utils
AnnotatingDomHelperswith both@category GUIand@category Utilscorrectly reflects its cross-cutting role. Verify that the TypeDoc category order (GUIbeforeUtils) matches intended documentation layout.
154-158: CategorizedeventUtilsunder Event & Utils
Applying@category Eventalongside@category Utilsaccurately groupseventUtilsas an event-related helper within the utilities section.
222-226: Dual categories forguiUtils: GUI & Utils
MarkingguiUtilsunder both@category GUIand@category Utilsis consistent with its functionality. Confirm the final ordering in the generated docs is as expected.packages/core/src/types.ts (6)
37-38: CategorizeUndoableChangeunder Change
Adding@category Changeto theUndoableChangetype brings it in line with other undoable change classes and supports clearer documentation grouping.
1158-1162: Group core event types under Event
Each of the event-related types (Listener,ListenerTarget,Listenable,MouseEventListener,KeyboardEventListener,GestureEvent,MouseListenerSet,EventCache) has been correctly annotated with@category Event, enhancing their discoverability in the API reference.Also applies to: 1164-1168, 1170-1175, 1177-1181, 1184-1189, 1191-1193
1209-1210: CategorizePopupMenuItemunder GUI
The@category GUItag on thePopupMenuIteminterface aligns it with other GUI constructs (e.g.,DomHelpers,MaxForm) for coherent documentation.
974-976: AddShapecategory to shape-related value types
The supplementary@category Shapetags onShapeValueandStyleShapeValuecomplement their existing@category Styleannotations, properly grouping them under shape primitives in the generated docs.Also applies to: 1013-1015
1440-1442: CategorizeShapeConstructorunder Shape
TaggingShapeConstructorwith@category Shapeensures consistent placement alongside other shape-related types and constructors.
1484-1486: CategorizeElbowValueunder Style
Applying@category StyletoElbowValueappropriately groups this style-specific type with other style value types, improving clarity in documentation.
|
1 participant
Attach more elements to specific categories to better group them in the HTML API documentation
Add new categories:
Reduce the number of typedoc warnings.
Also improve the JSDoc in various places.
Summary by CodeRabbit