Teaching Doxygen Nasal: Difference between revisions
mNo edit summary |
mNo edit summary |
||
Line 5: | Line 5: | ||
=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 | * 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 [ | * 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 | ||
Line 26: | Line 26: | ||
We were recently talking about teaching the wiki (GeSHi actually) Nasal, so that syntax highlighting is working properly here. | We were recently talking about teaching the wiki (GeSHi actually) Nasal, so that syntax highlighting is working properly here. | ||
= Related = | |||
* http://www.stack.nl/~dimitri/doxygen/index.html | |||
* http://www.stack.nl/~dimitri/doxygen/manual.html | |||
[[Category:Nasal]] | [[Category:Nasal]] |
Revision as of 18:08, 6 January 2012
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". 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
- 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)
- Ideally, we'll be able to reuse existing tools
- such as doxygen, to automatically parse Nasal code and create API docs
- 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
- doxygen supports several output formats, including LaTex/PDF
Language docs
- Nasal language (keywords, syntax)
- Nasal core library
- Nasal/FG extension functions
- FG Nasal APIs in $FG_ROOT/Nasal
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.
We already have a vim syntax highlighting fiel for Nasal here: http://gitorious.org/fg/flightgear/blobs/next/scripts/syntax/nasal.vim
This contains most important keywords. And this might be useful to get a doxygen mode started for Nasal.
We were recently talking about teaching the wiki (GeSHi actually) Nasal, so that syntax highlighting is working properly here.