4,400
edits
Teaching Doxygen Nasal: Difference between revisions
Jump to navigation
Jump to search
m
Link to special directory articles
No edit summary |
m (Link to special directory articles) |
||
| 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 Adrian suggested looking into Doxygen and using source code comments to come up with automatically created docs. | 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= | ||
* We want to automatically create API docs for $FG_ROOT/Nasal (i.e. the shared Nasal lib). | * We want to automatically create API docs for [[$FG_ROOT]]/Nasal (i.e. the shared Nasal lib). | ||
* Nasal is already very close to ECMA/JavaScript, C, C++ and Java (supported by DoxyGen already) | * Nasal is already very close to ECMA/JavaScript, C, C++ and Java (supported by DoxyGen already) | ||
* Ideally, we'll be able to reuse existing tools | * Ideally, we'll be able to reuse existing tools | ||
* such as [http://www.stack.nl/~dimitri/doxygen/index.html doxygen], to automatically parse Nasal code and create API docs | * such as [http://www.stack.nl/~dimitri/doxygen/index.html doxygen], to automatically parse Nasal code and create API docs | ||
* alternatively, the Nasal parser itself could be used | * alternatively, the Nasal parser itself could be used | ||
* 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 | ||
| Line 21: | Line 21: | ||
* Nasal core library | * Nasal core library | ||
* Nasal/FG extension functions | * Nasal/FG extension functions | ||
* FG Nasal APIs in $FG_ROOT/Nasal : a simple API has been generated with a python script; see here: http://www.flightgear.org/forums/viewtopic.php?f=30&t=15133 | * FG Nasal APIs in [[$FG_ROOT]]/Nasal : a simple API has been generated with a python script; see here: http://www.flightgear.org/forums/viewtopic.php?f=30&t=15133 | ||
= Summary = | = Summary = | ||
So, teaching doxygen Nasal would be a great contribution, then we could easily run doxygen against $FG_ROOT/Nasal and automatically create API docs. The core language is unlikely to change significantly, and library/extension functions could be added manually to the docs. | So, teaching doxygen Nasal would be a great contribution, then we could easily run doxygen against [[$FG_ROOT]]/Nasal and automatically create API docs. The core language is unlikely to change significantly, and library/extension functions could be added manually to the docs. | ||
We already have a vim syntax highlighting fiel for Nasal here: http://gitorious.org/fg/flightgear/blobs/next/scripts/syntax/nasal.vim | We already have a vim syntax highlighting fiel for Nasal here: http://gitorious.org/fg/flightgear/blobs/next/scripts/syntax/nasal.vim | ||