223
edits
Teaching Doxygen Nasal: Difference between revisions
Jump to navigation
Jump to search
no edit summary
m (→Related) |
No edit summary |
||
| Line 1: | Line 1: | ||
= Intro = | = Intro = | ||
This was an idea that we talked about on the forums: We still don't have any in-depth API docs for Nasal. We tried to come up with something like this several times already, but so far we failed. Also, it'd probably be a lot of work, too. Especially, because $FG_ROOT/Nasal is a "moving target". | This was an idea that we talked about on the forums: We still don't have any in-depth API docs for Nasal. We tried to come up with something like this several times already, but so far we failed. Also, it'd probably be a lot of work, too. Especially, because $FG_ROOT/Nasal is a "moving target". | ||
Most of the shared Nasal library in $FG_ROOT/Nasal is actually pretty well commented. So | Most of the shared Nasal library in $FG_ROOT/Nasal is actually pretty well commented. So Adrian suggested looking into Doxygen and using source code comments to come up with automatically created docs. | ||
=Goals= | =Goals= | ||
| Line 11: | Line 11: | ||
* API docs should be hosted at flightgear.org and included as part of each release in $FG_ROOT/Docs | * API docs should be hosted at flightgear.org and included as part of each release in $FG_ROOT/Docs | ||
* doxygen supports several output formats, including LaTex/PDF | * doxygen supports several output formats, including LaTex/PDF | ||
=Challenges= | |||
* Namespaces are based on files, rather than an internal structure. While this loose association benefits developing speed, any API document tool would have to take this into account. | |||
* The code is not uniformly documented, and there are no decorators which are typically used by documentation tools. | |||
* Perhaps as an intermediate step it would be worth investigating other tools as well, such as JSdoc, YUIdoc, or even writing a parser to extract FG Nasal APIs from the source even without decorative comments, listing just function names, parameters, and the namespace from which they can be accessed, along with any comments describing the functions, regardless of the presence of decorative elements. | |||
= Language docs = | = Language docs = | ||