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

Add custom JSDoc "expects" tag #183

Open
christianechevarria opened this issue Nov 7, 2019 · 1 comment
Open

Add custom JSDoc "expects" tag #183

christianechevarria opened this issue Nov 7, 2019 · 1 comment
Labels
😌 code quality For improvements to the syntax, structure, dependencies, etc... 🙌 community By or for the library's community 📖 documentation Regarding the documentation of a thing

Comments

@christianechevarria
Copy link
Member

christianechevarria commented Nov 7, 2019

Is your feature request related to a problem? Please describe.
Minimized code will have implicit assumptions baked into it. Ideally no assumptions would ever be made but this would create repeated work. So it's desirable to trust that arguments will conform to certain standards e.g. an array is sorted or a property is set

Describe the solution you'd like
As a way to make assumptions built into code explicit we could add a custom JSDoc @assumption that would go above the function declaration and render in the docs for a end-user consuming the software

Edit: As a way to shorten the syntax and broaden the applicability of the tag we could use @expects for interface related assumptions

@christianechevarria christianechevarria added 📖 documentation Regarding the documentation of a thing 🙌 community By or for the library's community 😌 code quality For improvements to the syntax, structure, dependencies, etc... labels Nov 7, 2019
@christianechevarria christianechevarria changed the title Add custom JSDoc "assumption" tag Add custom JSDoc "expects" tag Nov 7, 2019
@christianechevarria
Copy link
Member Author

The code for this is already present within the JSDoc template files as support was added for @alpha and @beta tags in ef21b99 and we could use the same method to resolve this issue

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
😌 code quality For improvements to the syntax, structure, dependencies, etc... 🙌 community By or for the library's community 📖 documentation Regarding the documentation of a thing
Projects
None yet
Development

No branches or pull requests

1 participant