Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: refine API docs for files in Command dir #1906

Merged
merged 3 commits into from
Nov 3, 2024

Conversation

devvaannsh
Copy link
Contributor

The following changes are made:-

API Documentation Cleanup:
Removed all internal details from the API docs.
Now, only the exports.* content is included.

DefaultMenus.js Exclusion:
This file is internal, so it won’t show up in the API docs anymore.

Refactor in Menus.js:
The object literals inside MenuSection are now declared separately and assigned to the MenuSection object afterward.
This doesn’t affect any existing functionality.
The change was made because Docusaurus had trouble parsing nested object literals when generating markdown, which caused errors.

@devvaannsh
Copy link
Contributor Author

The tests were failing because in file Menus.js, the variables were used before they were initialized! Fixed the issue!

Copy link
Member

@abose abose left a comment

Choose a reason for hiding this comment

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

We need to add the following docs too:

  • Commands.js - The well known exported command IDs needs to be in the docs somehow. maybe use enum?
  • KeyBindingManager.js
  • KeyboardOverlayMode.js
  • Keys.js - maybe use enum?

Tracked in #1922

src/command/CommandManager.js Outdated Show resolved Hide resolved
@devvaannsh
Copy link
Contributor Author

devvaannsh commented Nov 1, 2024

In keybindingManager.js, the @private tags are placed after the function description. Why? Because the jsdoc-2-md library showed a warning that @private tags cannot have a description. So, if @private is defined above the description, it mistakenly treats the description as part of @private.

In keybindingManager.js, the @type tag for UN_SWALLOWED_EVENTS was changed from {(string)[]} to {Array.}, because the former format is invalid and throws an error.

In Commands.js, each export needs to be handled separately. JSDoc should be added for each export individually so that they show up correctly in the API docs.

Copy link

sonarqubecloud bot commented Nov 1, 2024

@abose abose merged commit 4b202c8 into phcode-dev:main Nov 3, 2024
16 of 17 checks passed
@abose
Copy link
Member

abose commented Nov 3, 2024

LGTM. Thanks for contributing @devvaannsh

@devvaannsh devvaannsh deleted the command branch November 7, 2024 07:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants