2,734
edits
Teaching Doxygen Nasal: Difference between revisions
Jump to navigation
Jump to search
A bit of cleanup
m (Update forum links) |
Red Leader (talk | contribs) (A bit of cleanup) |
||
| Line 1: | Line 1: | ||
= | {{Nasal Navigation}} | ||
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". | |||
== Introduction == | |||
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/ | * such as [http://www.stack.nl/~dimitri/doxygen/ 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 | ||
=Challenges= | == Challenges == | ||
* Namespaces are based on files, rather than an internal structure. While this loose association benefits developing speed, any API document tool would have to take this into account. | * Namespaces are based on files, rather than an internal structure. While this loose association benefits developing speed, any API document tool would have to take this into account. | ||
* The code is not uniformly documented, and there are no decorators which are typically used by documentation tools. | * The code is not uniformly documented, and there are no decorators which are typically used by documentation tools. | ||
* Perhaps as an intermediate step it would be worth investigating other tools as well, such as JSdoc, YUIdoc, or even writing a parser to extract FG Nasal APIs from the source even without decorative comments, listing just function names, parameters, and the namespace from which they can be accessed, along with any comments describing the functions, regardless of the presence of decorative elements. | * Perhaps as an intermediate step it would be worth investigating other tools as well, such as JSdoc, YUIdoc, or even writing a parser to extract FG Nasal APIs from the source even without decorative comments, listing just function names, parameters, and the namespace from which they can be accessed, along with any comments describing the functions, regardless of the presence of decorative elements. | ||
= Language docs = | == Language docs == | ||
* Nasal language (keywords, syntax) | * Nasal language (keywords, syntax) | ||
* 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 | * FG Nasal APIs in [[$FG_ROOT]]/Nasal: a simple API has been generated with a python script; see [http://forum.flightgear.org/viewtopic.php?f=30&t=15133 here] | ||
== 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 | We already have a vim syntax highlighting field for Nasal {{flightgear file|scripts/syntax/nasal.vim|t=here}} | ||
This contains most important keywords. And this might be useful to get a Doxygen mode started for Nasal. | |||
= Modifying Doxygen = | == Modifying Doxygen == | ||
The | The Doxygen internals (architecture) are described [http://www.stack.nl/~dimitri/doxygen/manual/arch.html here] | ||
According to the docs, the parser is based on | According to the docs, the parser is based on {{wikipedia|Flex (lexical analyser generator)|Flex}} | ||
* "The preprocessed input buffer is fed to the language parser, which is implemented as a big state machine using flex. It can be found in the file [http:// | * "The preprocessed input buffer is fed to the language parser, which is implemented as a big state machine using flex. It can be found in the file [http://sourceforge.net/p/doxygen/code/HEAD/tree/trunk/src/scanner.l src/scanner.l]. There is one parser for all languages (C/C++/Java/IDL). The state variables insideIDL and insideJava are uses at some places for language specific choices." | ||
* "The task of the parser is to convert the input buffer into a tree of entries (basically an abstract syntax tree). An entry is defined in src/entry.h and is a blob of loosely structured information. The most important field is section which specifies the kind of information contained in the entry." | * "The task of the parser is to convert the input buffer into a tree of entries (basically an abstract syntax tree). An entry is defined in src/entry.h and is a blob of loosely structured information. The most important field is section which specifies the kind of information contained in the entry." | ||
The Doxygen repository can be found [http://sourceforge.net/p/doxygen/code/HEAD/tree/ here]. | |||
== External links == | |||
= | |||
* http://www.stack.nl/~dimitri/doxygen/index.html | * http://www.stack.nl/~dimitri/doxygen/index.html | ||
* http://www.stack.nl/~dimitri/doxygen/manual.html | * http://www.stack.nl/~dimitri/doxygen/manual.html | ||
* http://www.codeguru.com/csharp/.net/net_general/patterns/article.php/c12805 | * http://www.codeguru.com/csharp/.net/net_general/patterns/article.php/c12805/Classic-Parsing-with-Flex-and-Bison.htm | ||
* http://www.mactech.com/articles/mactech/Vol.16/16.07/UsingFlexandBison/index.html | * http://www.mactech.com/articles/mactech/Vol.16/16.07/UsingFlexandBison/index.html | ||
* http://ds9a.nl/lex-yacc/cvs/lex-yacc-howto.html | * http://ds9a.nl/lex-yacc/cvs/lex-yacc-howto.html | ||
[[Category:Nasal]] | [[Category:Nasal]] | ||