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.