Board index FlightGear Development Nasal

Nasal API Docs for $FG_ROOT/Nasal

Nasal is the scripting language of FlightGear.

Nasal API Docs for $FG_ROOT/Nasal

Postby adrian » Fri Jan 27, 2012 12:38 pm

I have generated a simple Nasal API file for $FG_ROOT/Nasal with a python script.
I have uploaded the file here
This is a temporary solution until there's a more solid solution. The reasons I've used a home-made parser instead of a pre-made solution is the lack of uniform coding and comment style. There's a lot to be improved, for sure. For one, I would like to extend it further so it can parse classes as well.
Please take a look and comment.
adrian
 
Posts: 362
Joined: Wed Sep 15, 2010 2:15 pm

Re: Nasal API for $FG_ROOT/Nasal

Postby Hooray » Fri Jan 27, 2012 1:43 pm

hey, that's cool - we need to make sure that this is committed to $FG_ROOT/Docs - and your Python script should go into the contrib directory, too!

The coloring takes a while getting used to (maybe it's just me?)- but apart from that, it's really cool, and coloring can be simply changed using CSS.
Personally, I'd suggest something along the lines of the official Nasal web page instead: http://plausible.org/nasal/lib.html

Navigation-wise I don't have any comments, it's working for me.

Thanks!
Please don't send support requests by PM, instead post your questions on the forum so that all users can contribute and benefit
Thanks & all the best,
Hooray
Help write next month's newsletter !
pui2canvas | MapStructure | Canvas Development | Programming resources
Hooray
 
Posts: 11191
Joined: Tue Mar 25, 2008 8:40 am

Re: Nasal API for $FG_ROOT/Nasal

Postby adrian » Fri Jan 27, 2012 5:06 pm

I still need to sort out some of the comments and other little details. I've changed the colours to fit the original theme.
Preview here
Some functions are not parsed because they override a global variable, which according to the wiki is a no no. Fortunately they are few.
after I'm finished and happy that the parser is solid, we'll see if we can translate this into an online reference as well, wiki or otherwise.
adrian
 
Posts: 362
Joined: Wed Sep 15, 2010 2:15 pm

Re: Nasal API for $FG_ROOT/Nasal

Postby adrian » Fri Jan 27, 2012 6:44 pm

Updated
Most of the issues are gone by now. Could use another pair of eyes to check for inconsistencies.
adrian
 
Posts: 362
Joined: Wed Sep 15, 2010 2:15 pm

Re: Nasal API for $FG_ROOT/Nasal

Postby Hooray » Fri Jan 27, 2012 8:12 pm

Looks great, even better than the previous version!

Here are just a few comments regarding parsing:

  • you might want to look into replacing ===... with <hr/> instead?
  • maybe use a bigger font/formatting style for the descriptions added (e.g. <h4>) ?
  • similarly, maybe use a different style for all paragraphs that contain keywords like SYNOPSIS/EXAMPLE* ?
  • maybe add links to the gitorious files for each Nasal module, possibly using line numbers, too? http://gitorious.org/fg/fgdata/blobs/ma ... .nas#line9
  • Nasal functions that have a prepended underscore, are by convention low level ("private"/internal) functions - maybe highlight differently?

This is already great and much better than anything we've had before - so don't worry about my comments ;-)
But if there's any more info you'd like to get out of the sources, I could help you hacking the SG/Nasal parser to directly dump the AST to an XML/RDF file that we could process using XSLT to create an XHTML file.
Please don't send support requests by PM, instead post your questions on the forum so that all users can contribute and benefit
Thanks & all the best,
Hooray
Help write next month's newsletter !
pui2canvas | MapStructure | Canvas Development | Programming resources
Hooray
 
Posts: 11191
Joined: Tue Mar 25, 2008 8:40 am

Re: Nasal API for $FG_ROOT/Nasal

Postby adrian » Fri Jan 27, 2012 8:59 pm

I'll look into 1,2 and 5. Can't promise anything about 3, due to the way the comments are. 4 is doable, maybe a bit later after this is reviewed.
About XML/RDF, sure, if you want to, but the Nasal code is pretty fast and loose, and so is the parser :D Of course we can extend it in any way possible.
adrian
 
Posts: 362
Joined: Wed Sep 15, 2010 2:15 pm

Re: Nasal API for $FG_ROOT/Nasal

Postby Hooray » Sat Jan 28, 2012 7:07 am

For one, I would like to extend it further so it can parse classes as well.


This is another thing where Nasal's "flexibility" might be tricky - there are different ways to specify classes, but the most standard/common method (certainly for code in $FG_ROOT/Nasal) is embedding all methods inline and providing a "new" method that initializes the parents vector to the name of the enclosing hash.
Another indicator would be hash functions (methods) that are making use of the "me" keyword.

Code: Select all
var foo = {
 new: func {
   var temp = { parents:[foo] };
   return temp;
 }
};


So, basically whenever your parser is parsing a hash expression, it would need to 1) look for a "new: func", 2) look for the "parents" keyword, 3) look for the "me" keyword.
Once you've found a hash that matches these heuristics, it's pretty safe to assume that you are dealing with a "class".

I don't know anything about your parser (hand-coded or using an existing parser framework?), but I assume it would be easier to patch the Nasal parser so that it can dump the internal AST, simply because that should already contain all the info. Just saying this, in case you are not interested in re-implementing a Nasal parser in Python :-)
Please don't send support requests by PM, instead post your questions on the forum so that all users can contribute and benefit
Thanks & all the best,
Hooray
Help write next month's newsletter !
pui2canvas | MapStructure | Canvas Development | Programming resources
Hooray
 
Posts: 11191
Joined: Tue Mar 25, 2008 8:40 am

Re: Nasal API for $FG_ROOT/Nasal

Postby adrian » Sat Jan 28, 2012 12:49 pm

Class parsing is already done, check the api :)
I'm quite pleased with the resulting api description right now, so until there's a solid interest in having a more bullet-proof solution, I think it fits the purpose. Of course, it can always be extended should the need arise.
adrian
 
Posts: 362
Joined: Wed Sep 15, 2010 2:15 pm

Re: Nasal API for $FG_ROOT/Nasal

Postby Hooray » Sat Jan 28, 2012 6:07 pm

I agree, it's already excellent as is. So, I think this should be added to the repository - the resulting HTML file, as well as the parser script. You should probably file a merge request. Which should be a no brainer, because it doesn't touch any existing stuff.

The heuristics I came up with were just meant to properly handle hashes that are not OOP related.

Today, I noticed that there's a minor issue related to the navigation bar - i.e. not everything is visible (and not scrollable either) if the screen dimensions/resolution are not sufficient.

formatting-wise, the HTML output could use different style for optional function arguments. The Nasal standard library uses an EBNF-based specification format:

timer.new(<property> [, <resolution:double> [, <save:bool>]])

Also, the type of parameter is often specified using a colon: variabe:type

So, this is at least some information that could be extracted and further processed if desired.

Apart from that, I agree that most of the comments are not yet specified in a sufficiently uniform fashion.
One of the more common cases seems to be:

Code: Select all
###################
# function description
###################


Navigation-wise, I'd suggest to differentiate between Nasal standard library modules, whose namespaces are based on the file names, and Nasal "sub modules", whose namespaces are based on the folder name.

If the parser could be taught to differentiate here, it would be smarter about linking modules to namespaces. This would in turn make it possible to provide a tabbed interface, where the API docs could be grouped into FILES | NAMESPACES | MODULES | CLASSES | FUNCTIONS

But that way, it would also be possible to directly link examples/use cases to each API, by using a reverse lookup (namespace.function) and linking to the filename,line number of matching occurrences.

This would be in line with the way DoxyGen docs structure the output. If you'd like to pursue this, I can help you coming up with the XPATH stuff to create these views dynamically using DHTML.
Please don't send support requests by PM, instead post your questions on the forum so that all users can contribute and benefit
Thanks & all the best,
Hooray
Help write next month's newsletter !
pui2canvas | MapStructure | Canvas Development | Programming resources
Hooray
 
Posts: 11191
Joined: Tue Mar 25, 2008 8:40 am

Re: Nasal API for $FG_ROOT/Nasal

Postby Hooray » Mon Jan 30, 2012 10:28 am

similarly, maybe use a different style for all paragraphs that contain keywords like SYNOPSIS/EXAMPLE* ?


We could use a vector of "identifier" strings here that contains all important keywords, these could then be recognized and wrapped inside <b></b> tags.

The core library comments are pretty standard actually, because the code was largely written by a single person:

EXAMPLE:
EXAMPLES:
SYNOPSIS:
SIGNALS:
USAGE:
PARAMETERS:
WARNING:
TODO:
SIMPLE USE:
ADVANCED USE:
ARGUMENTS:

So, all that is needed is a case-insensitive check to change the markup of such keywords.

Once this is working, we could look into further standardizing the comments in $FG_ROOT/Nasal by removing duplicates (e.g. ARGUMENTS vs. PARAMETERS, would be a simple sed run) and adding new comments, so that your script can automatically create even better docs.
Please don't send support requests by PM, instead post your questions on the forum so that all users can contribute and benefit
Thanks & all the best,
Hooray
Help write next month's newsletter !
pui2canvas | MapStructure | Canvas Development | Programming resources
Hooray
 
Posts: 11191
Joined: Tue Mar 25, 2008 8:40 am


Return to Nasal

Who is online

Users browsing this forum: No registered users and 3 guests