Teaching Doxygen Nasal

From FlightGear wiki
Revision as of 18:02, 6 January 2012 by Hooray (talk | contribs) (initial draft)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

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