Teaching Doxygen Nasal: Difference between revisions

From FlightGear wiki
Jump to navigation Jump to search
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 [[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
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.

Related