Conversation
Apply existing categories to more elements. Add categories: - Editor - GUI - Style JSDoc HTML documentation: include categories in the navigation to ease the organization Also improve JSDoc in some classes and functions.
WalkthroughThis pull request makes extensive updates to documentation comments and JSDoc annotations across many modules in the codebase. The changes reformat descriptions, update example code to modern JavaScript conventions (using Changes
Possibly related PRs
📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (3)
🚧 Files skipped from review as they are similar to previous changes (3)
🪧 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 (
|
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (3)
packages/core/src/gui/MaxLogAsLogger.ts (1)
27-29: JSDoc Category Addition: GUI and Logging
The addition of@category GUIand@category Loggingclarifies the categorization of theMaxLogAsLoggerclass. Please verify that the use of multiple categories here is intentional and that the generated documentation will display them as expected.packages/core/src/view/cell/register-shapes.ts (1)
42-45: JSDoc Update: Added Versioning and Dual Categories
The inclusion of@since 0.8.0along with both@category Configurationand@category Stylehelps clarify the function’s version history and its dual role in configuration and styling. Please confirm that dual categorization meets your documentation standards.packages/core/src/view/style/StyleRegistry.ts (1)
20-22: Suggestion: Verify Terminology in Description
The phrase “used to perimeters and edge styles” appears ambiguous. Consider revising it for clarity (e.g., “used for handling perimeters and edge styles”) if that better reflects the intended functionality.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (24)
packages/core/src/editor/Editor.ts(1 hunks)packages/core/src/editor/EditorKeyHandler.ts(1 hunks)packages/core/src/editor/EditorPopupMenu.ts(1 hunks)packages/core/src/editor/EditorToolbar.ts(2 hunks)packages/core/src/gui/MaxForm.ts(1 hunks)packages/core/src/gui/MaxLog.ts(1 hunks)packages/core/src/gui/MaxLogAsLogger.ts(1 hunks)packages/core/src/gui/MaxPopupMenu.ts(1 hunks)packages/core/src/gui/MaxToolbar.ts(1 hunks)packages/core/src/gui/MaxWindow.ts(1 hunks)packages/core/src/i18n/Translations.ts(1 hunks)packages/core/src/i18n/config.ts(1 hunks)packages/core/src/serialization/register-model-codecs.ts(1 hunks)packages/core/src/serialization/register-other-codecs.ts(3 hunks)packages/core/src/types.ts(10 hunks)packages/core/src/util/MaxXmlRequest.ts(3 hunks)packages/core/src/view/cell/register-shapes.ts(1 hunks)packages/core/src/view/geometry/edge/MarkerShape.ts(1 hunks)packages/core/src/view/style/EdgeStyle.ts(1 hunks)packages/core/src/view/style/StyleRegistry.ts(1 hunks)packages/core/src/view/style/Stylesheet.ts(1 hunks)packages/core/src/view/style/config.ts(6 hunks)packages/core/src/view/style/register.ts(1 hunks)packages/core/tsconfig.json(1 hunks)
🔇 Additional comments (53)
packages/core/src/util/MaxXmlRequest.ts (3)
222-225: Improved Documentation for getStatus Method
The updated JSDoc forgetStatusnow correctly uses "e.g." instead of "eg." and clearly explains the expected numeric status codes. This change enhances both grammatical correctness and clarity.
242-249: Clarified JSDoc for send Method
The revised documentation for thesendmethod now explicitly notes that theonerrorparameter is ignored (due to technical limitations) and that it is intended for override. This additional clarification improves the reader’s understanding of the method’s behavior.
519-524: Enhanced JSDoc for post Function
The updated JSDoc for thepostfunction now cleanly explains that the parameters will be posted asynchronously and emphasizes the need to useencodeURIComponentfor parameter values. This clear description will help maintain consistency across documentation and assists developers in correct usage.packages/core/src/view/geometry/edge/MarkerShape.ts (1)
256-258: Documentation improvement: Added style categoryGood addition of
@since 0.11.0and@category Styletags to properly categorize theregisterDefaultEdgeMarkersfunction. This enhancement improves documentation organization and aligns with the PR objectives.packages/core/src/view/style/register.ts (1)
27-29: Documentation improvement: Added style category and version informationThe addition of
@since 0.8.0and@category Styletags to theregisterDefaultStyleElementsfunction enhances the documentation by providing version information and proper categorization, which aligns perfectly with the PR objectives.packages/core/src/serialization/register-model-codecs.ts (1)
43-43: Documentation improvement: Added serialization categoryGood addition of the
@category Serialization with Codecstag to properly categorize theregisterModelCodecsfunction. This enhancement improves the organization of documentation and helps users better understand the purpose of this function.packages/core/src/view/style/config.ts (6)
27-27: Documentation improvement: Added EdgeStyle categoryGood addition of the
@category EdgeStyletag to enhance the categorization of theEntityRelationConnectorConfigconfiguration object.
44-44: Documentation improvement: Added EdgeStyle categoryGood addition of the
@category EdgeStyletag to enhance the categorization of theresetEntityRelationConnectorConfigfunction.
57-57: Documentation improvement: Added EdgeStyle categoryGood addition of the
@category EdgeStyletag to enhance the categorization of theOrthogonalConnectorConfigconfiguration object.
84-84: Documentation improvement: Added EdgeStyle categoryGood addition of the
@category EdgeStyletag to enhance the categorization of theresetOrthogonalConnectorConfigfunction.
126-126: Documentation improvement: Added EdgeStyle categoryGood addition of the
@category EdgeStyletag to enhance the categorization of theManhattanConnectorConfigconfiguration object.
144-144: Documentation improvement: Added EdgeStyle categoryGood addition of the
@category EdgeStyletag to enhance the categorization of theresetManhattanConnectorConfigfunction.packages/core/src/view/style/EdgeStyle.ts (1)
81-83: JSDoc Category Added for EdgeStyle
The documentation now includes the@category EdgeStyletag, which improves the organization and discoverability of this class in the generated docs. This change is straightforward and aligns well with the new documentation standards.packages/core/src/gui/MaxPopupMenu.ts (1)
50-52: JSDoc Enhancement for GUI Components
The inclusion of the@category GUItag in the JSDoc comment clarifies thatMaxPopupMenuis part of the GUI layer. This helps in better categorizing documentation without affecting functionality.packages/core/src/gui/MaxLog.ts (1)
31-33: Enhanced JSDoc with Multiple Categories
The addition of both@category GUIand@category Loggingtags to theMaxLogclass refines its classification. This dual categorization neatly indicates that the class plays a role in both GUI-related operations and logging functionality.packages/core/src/view/style/Stylesheet.ts (1)
46-48: Added JSDoc Category for Styling
The new@category Styletag in the documentation for theStylesheetclass helps in grouping style-related functionalities. This update should enhance navigation in the generated documentation and follows the documentation consistency improvements seen across the codebase.packages/core/src/gui/MaxToolbar.ts (1)
46-47: JSDoc Categorization Update for GUI Components
Adding the@category GUItag to theMaxToolbarclass documentation is a clear improvement, making it easier for developers to locate and understand GUI-related components in the codebase.packages/core/src/i18n/Translations.ts (1)
75-77: JSDoc Category Addition: I18n
Adding the@category I18ntag organizes theTranslationsclass under internationalization, which aligns well with the overall documentation improvements.packages/core/src/gui/MaxForm.ts (1)
27-27: JSDoc Update: Categorization as GUI
The updated JSDoc for theMaxFormclass now includes the@category GUIannotation, which improves the clarity and navigability of the documentation for GUI-related components.packages/core/src/view/style/StyleRegistry.ts (1)
19-25: JSDoc Enhancement: Improved Formatting and Category Inclusion
The restructuring of the documentation comment—with the consolidation of the description and the insertion of the@category Styletag—greatly improves clarity and consistency.packages/core/src/gui/MaxWindow.ts (1)
179-179: Good addition of category tag for improved documentation organization.Adding the
@category GUItag to the MaxWindow class helps organize the documentation and makes it easier to navigate related components.packages/core/src/serialization/register-other-codecs.ts (3)
70-70: Documentation enhancement with new category tag.Adding the
@category Serialization with Codecstag to theregisterCoreCodecsfunction improves documentation organization while maintaining the existing@category Configurationtag.
95-95: Documentation enhancement with new category tag.Adding the
@category Serialization with Codecstag to theregisterEditorCodecsfunction improves documentation organization while maintaining the existing@category Configurationtag.
117-117: Documentation enhancement with new category tag.Adding the
@category Serialization with Codecstag to theregisterAllCodecsfunction improves documentation organization while maintaining the existing@category Configurationtag.packages/core/src/i18n/config.ts (2)
40-50: Good addition of a utility function to reset translations configuration.The new
resetTranslationsConfigfunction with proper JSDoc documentation provides a convenient way to reset translations to default values. The experimental tag is appropriate since this is related to global configuration that may change in the future.
54-58: Enhanced documentation for TranslationsConfig.The updated JSDoc for TranslationsConfig now properly indicates its experimental status and adds the I18n category tag, providing better documentation organization.
packages/core/src/editor/EditorToolbar.ts (4)
33-37: Improved class documentation formatting and clarity.The description has been concisely updated to "Toolbar for the editor" with proper markdown formatting using "### Example" which aligns with modern documentation standards.
44-47: Updated example code to use modern JavaScript conventions.Good update from
vartoconstin the example code, which follows modern JavaScript best practices.
57-57: Added category tag for better documentation organization.The addition of
@category Editorhelps with documentation organization and makes related components easier to find.
122-122: Improved readability in comment.Changed "doubleclick" to "double click" for better readability and consistency with other documentation.
packages/core/src/editor/Editor.ts (2)
394-394: Documentation improvement with category additionThe addition of the
@category Editortag enhances the code's documentation by properly categorizing this class in the generated documentation. This aligns with the PR objective of adding JSDoc categories.
397-406: Improved constructor documentation with modern JavaScript syntaxThe updated constructor documentation is more concise and uses modern ES6 syntax with
constinstead ofvar. The parameter description has also been added for better clarity.packages/core/src/editor/EditorKeyHandler.ts (1)
25-46: Improved class documentation with better structure and modern syntaxThe documentation has been significantly improved with:
- More concise first line description
- Better explanation of class functionality
- Improved section headers using markdown syntax (### Example, ### Codec, ### Keycodes)
- Updated code example to use modern ES6 syntax with
const- Added
@category Editortag for proper categorizationThese changes align with the PR objective to enhance JSDoc documentation and apply consistent categorization.
packages/core/src/editor/EditorPopupMenu.ts (1)
28-39: Enhanced documentation with improved structure and categorizationThe class documentation has been restructured with:
- More concise first line description
- Better organized explanations with separate paragraphs
- Updated class reference from mxPopupMenu to MaxPopupMenu
- Improved section header format with markdown syntax (### Codec)
- Added
@category Editortag for proper categorizationThese changes contribute to better documentation readability and organization, aligning with the PR objectives.
packages/core/tsconfig.json (3)
18-18: Added excludeInternal option for TypeDocAdding
"excludeInternal": truewill ensure that internal symbols are excluded from the generated documentation, creating cleaner and more focused API documentation for users.
25-30: Added new JSDoc categories to TypeDoc configurationThe addition of new categories ("EdgeStyle", "Editor", "GUI", "I18n", "Style") and reorganization of existing ones supports the PR objective of adding more JSDoc categories for better documentation organization.
Also applies to: 34-34
39-39: Enabled categories in TypeDoc navigationChanging
includeCategoriesfromfalsetotrueensures that the newly defined categories will be included in the navigation structure of the generated documentation. This improves documentation browsing and organization.packages/core/src/types.ts (16)
38-39: LGTM! Good documentation enhancement.Adding the
@category Styletag toStyleValuetype helps organize your JSDoc documentation better.
43-69: LGTM! Appropriate categorization forCellStyle.The
@category Styletag is correctly added to theCellStyletype, enhancing documentation organization.
71-875: LGTM! Good documentation organization.Adding the
@category Styletag to the extensiveCellStateStyletype helps with JSDoc categorization.
877-882: LGTM! Appropriate categorization.The
@category Styletag is correctly added to theNumericCellStateStyleKeystype.
884-885: LGTM! Consistent categorization.The
@category Styletag is appropriately added to theColorValuetype.
886-889: LGTM! Enhanced documentation forSpecialStyleColorValue.Improved JSDoc comment with the
@category Styletag for better organization.
897-908: LGTM! Consistent categorization for style-related types.The
@category Styletags are appropriately added to all style value types, maintaining consistency.
911-911: LGTM! Appropriate categorization forArrowValue.The
@category Styletag is correctly added to the arrow-related type.
927-927: LGTM! Consistent categorization.The
@category Styletag is appropriately added to theStyleArrowValuetype.
933-933: LGTM! Appropriate categorization forShapeValue.The
@category Styletag is correctly added to the shapes-related type.
955-955: LGTM! Consistent categorization.The
@category Styletag is appropriately added to theStyleShapeValuetype.
1202-1204: LGTM! Added version information and categorization.The
@since 0.8.0and@category EdgeStyletags provide valuable metadata for theEdgeStyleFunctiontype.
1217-1217: LGTM! Appropriate categorization forEdgeStyleValue.The
@category EdgeStyletag is correctly added to the edge style-related type.
1232-1232: LGTM! Consistent categorization.The
@category EdgeStyletag is appropriately added to theStyleEdgeStyleValuetype.
1242-1242: LGTM! Appropriate categorization forMarkerFactoryFunction.The
@category Styletag is correctly added to the marker-related function type.
1088-1097:Details
✅ Verification successful
Added new
onDestroymethod toGraphPlugininterface.The
GraphPlugininterface has been enhanced with anonDestroymethod, which will require implementations to handle plugin cleanup. Make sure all existing plugin implementations are updated to include this method.Both interfaces are correctly categorized with
@category Plugintags.
🏁 Script executed:
#!/bin/bash # Check for existing plugin implementations that might need updates echo "Searching for GraphPlugin implementations that need to be updated with onDestroy method:" rg "class .+ implements GraphPlugin" -g "*.ts"Length of output: 1116
I'll run a further check to verify if the implementations of
GraphPlugininclude anonDestroymethod.
🏁 Script executed:
#!/bin/bash echo "Checking for onDestroy definitions in files implementing GraphPlugin..." rg -n "onDestroy" packages/core/src/view/handler/*.tsLength of output: 2343
Update Verified: GraphPlugin
onDestroyImplementationsThe new
onDestroymethod has been correctly added to theGraphPlugininterface, and our search confirms that all core classes implementingGraphPlugin(e.g., RubberBandHandler, TooltipHandler, PanningHandler, SelectionHandler, PopupMenuHandler, SelectionCellsHandler, ConnectionHandler, and CellEditorHandler) now include an implementation ofonDestroy. The categorization with@category Pluginremains intact.No further changes are needed for this update. Please ensure that any non-core or future plugin implementations also adhere to this updated cleanup contract.
|
Apply existing categories to more elements.
Add categories:
JSDoc HTML documentation: include categories in the navigation to ease the organization
Also improve JSDoc in some classes and functions.
Summary by CodeRabbit