Skip to content

Apply [] syntax for optional params to JSDoc @param tags #159

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

Closed
wants to merge 1 commit into from

Conversation

MajorLift
Copy link
Contributor

  • It can be tricky to tell whether or not a parameter is optional if they are passed in as object properties that might also be nested.
  • The JSDoc [] syntax gives a simple but clear visual indication of which params are optional.
  • This PR annotates all existing params that are defined using the ?: operator.

- It can be tricky to tell whether or not a parameter is optional if they are passed in as object properties that might also be nested.
- The JSDoc `[]` syntax gives a simple but clear visual indication of which params are optional.
@MajorLift MajorLift added the documentation Improvements or additions to documentation label Oct 13, 2023
@MajorLift MajorLift self-assigned this Oct 13, 2023
@MajorLift MajorLift requested a review from a team as a code owner October 13, 2023 22:09
Copy link
Contributor

@mcmire mcmire left a comment

Choose a reason for hiding this comment

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

I noticed you suggested these changes on #157. In the extension and mobile app you may see this technique, but that's because most of the files are still written using JavaScript. However, in projects that use TypeScript, we've stopped using it, because now any information related to types can be gleaned from TypeScript.

This is further explained by looking at where JSDoc is used:

  1. When writing code (i.e. hovering on a symbol). In this case, VSCode seems to ignore brackets around arguments. If you hover over a function, it doesn't show types for arguments at all; if you hover over an argument, it'll show you the type (which you specify separately).
  2. When viewing generated documentation. We use typedoc to generate documentation, and this tool does not read the brackets around arguments.
  3. When reading code. I guess looking over your PR description, that seems to be the main argument for adding this change. If you want to know whether an argument for a function is optional, though, I'm wondering if it's enough to look at the TypeScript types?

@MajorLift
Copy link
Contributor Author

I think the brackets might still be useful when function params are passed in as objects, and those types have nested optional properties.

For example, if we were to add a nested entry into ValidateChangeLogOptions like packageRename?: PackageRenameOptions and some properties of PackageRenameOptions were optional, JSDoc [] syntax highlighting makes it easy to identify the optional arguments at a glance, without having to click and hover our way through multiple types.

I guess the utility of doing this for all typescript projects is limited, though, if the language server and docgen don't utilize the brackets. Just stating "optional" in human language like we're doing now might be good enough.

@mcmire
Copy link
Contributor

mcmire commented Oct 16, 2023

Yeah. I mean, it's a good thought.

If you keep running into this and still think it would be valuable, I wonder if it would be better to find or add an ESLint rule around this so it could automatically add the brackets and they would be present without us having to think about it.

@MajorLift
Copy link
Contributor Author

It seems like there are no eslint rules for optional @param or @property tags, at least in eslint-plugin-jsdoc. I guess we could add the brackets if we come across a situation where they'd be especially useful, without enforcing consistent usage everywhere.

Closing this PR for now. Will revert b51a4fa as well.

@MajorLift MajorLift closed this Oct 16, 2023
@mcmire mcmire deleted the 231013-apply-jsdoc-optional-params-syntax branch October 24, 2023 18:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants