Teaching Doxygen Nasal

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
• 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.