Opened 8 years ago
Last modified 4 years ago
#4057 new enhancement
doxygen and JSdoc documentation — at Initial Version
| Reported by: | elexis | Owned by: | |
|---|---|---|---|
| Priority: | If Time Permits | Milestone: | Backlog |
| Component: | Website / Forum | Keywords: | contributor-experience |
| Cc: | Krinkle | Patch: |
Description
JSdoc (for JS) and doxygen comments (for C++) are used widely in the code and can be used to generate code documentation in HTML. Both tools can be run from the commandline, thus could be installed on a webserver to generate updated docs periodically (cronjob on unix) and present them online.
For JSDoc the docstrap templates seem nice: https://github.com/docstrap/docstrap
As comments should only state things which are not self-evident from the code, the use case of the online documentation will be to have a list of explanation of edge-cases and weird code behavior, while only showing function headers.
Still fairly limited, the benefit will apply to simulation components, like UnitAI, pathfinder, rangemanager, UnitMotion and libraries like the random map scripts (rather than the GUI which doesn't reuse complex code accross many files).
Refs https://wildfiregames.com/forum/index.php?/topic/20728-jsdoc-documentation/#comment-316064
