Avoid "Documentation Disillusionment"
Perhaps you've lived this scenario, or are living it now: You have created your masterwork of code and have been generally good at commenting your functions, classes, and types using JSDoc syntax. Then you run it through JSDoc and are dismayed to find that the code documentation is incomplete or incorrect in many cases, and you are forced to go back into your source code to find and fix bad or missing elements. It can be confusing because JSDoc has so many tags and not all of them work as you would expect.
Perhaps more frustrating: You are now using Typescript for your source code, and have adopted it for type declarations. But JSDoc does not work well with Typescript, and does not recognize your type declarations or class properties. Not to mention your own defined types or enums.
To document all these things properly you fear you will need to effectively learn to master another language in addition to your code -- JSDoc.
And you thought you were near the end of your project!
Instead, you need to buckle up for what may be several more weeks before you can get your code to parse into documentation that properly represents your API.
You can use alternatives, via JSDoc templates such as Better Docs or DocStrap, or alternative engines such as DocumentationJS, and these will likely give you prettier output, but may not solve the fundamental problems of having your code recognized and represented for what it is at the source level.
In rides Doc-Holiday
If the idea of shooting it out with JSDoc gives you a bad toothache from grinding your jaw, Doc-Holiday can help.
Take a break from the status-quo of documentation hell and get on with getting published.
The result: No more worrying about a "second syntax" to learn just to say again what you've already written in code for the sake of proper documentation. No more jumping through hoops to get documentation to be rendered as it should be.
In addition, Doc-Holiday comes with impressive features as well
- Uses existing JSDoc or DocumentationJS engines and templates, so your output can be styled as you like it to be.
- Recognizes and supports Typescript type declarations, enums, typedefs, interfaces, and more
- Recognizes and supports Mix-Ins
- Recognizes and supports basic JSDoc function comment blocks for @param and @return definitions if not provided by Typescript
- Supports multiple forms for comment descriptions.
- Supports adhoc use of JSDoc tags when needed for exceptional circumstances.
- Introduces Constraints to allow specification of value ranges in addition to type.
- Provides API support for runtime validation of Constraints, if desired.
- Supports PlantUML diagrams from within your description blocks.
- May be integrated into larger documentation processing pipelines through either module API or via CLI options.
Comprehensive documentation may be found here