[Tinyos] Re: [nescc-devel] nesdoc and nesC 1.2 - 1 or 2 volunteers needed!

[David Gay]

On 7/28/05, David Gay <david.e.gay at intel.com> wrote:
> nesdoc (which generates the web pages describing the tinyos components
> and interfaces, as well as wiring graphs for whole applications) needs
> updating for the new language features in nesC 1.2 (generic components,
> binary components). Rather than hack the existing code, this seems like
> a good occasion to rewrite the documentation generation based on the new
>   XML output facilities added for nesC 1.2. This should hopefully make
> the nesdoc code more maintainable and more flexible (see below).
> 
> Some help on implementing this would:
> - give me more time to deal with other nesC issues ;-)
> - allow you to produce an even better nesdoc
> 
> See the tasks at the end to see what's needed; the stuff in between
> explains those tasks... Email me if you want to work on this.

Btw, I'm planning to get this done in the next 2-3 weeks.

> Overview of the new XML output features
> ---------------------------------------
> - you can compile a nesC application with
> 
>     -fsyntax-only -fnesc-dump=<dump request>
> 
>    and get lots of useful info.
> 
>    For instance, if you compile Blink with
> 
>      ncc -fsyntax-only -fnesc-dump=interfaces -fnesc-dump=components
> -fnesc-dump=interfacedefs -fnesc-dump=wiring Blink.nc
> 
>    you'll receive lots of XML output describing:
> - The interfaces used and provided by all of Blink's components
> - A list of all of Blink's components
> - The definition of all the interfaces used by Blink
> - Blink's wiring graph
> 
>    This is most of the information needed to do the work nesdoc
> currently does, I'll be adding the missing bits (documentation strings,
> per-component wiring graphs and a few others) shortly.
> 
> - you can filter these dump requests, and do a few other things
> (probably not relevant to documentation generation though).
> 
> Reimplementing nesdoc using the XML output stuff
> ------------------------------------------------
> 
> I believe the right way to structure the new nesdoc is:
> - when nesdoc is run on app X, it does three things:
> 
>    - it runs ncc on X with the -fnesc-dump options to extract all the
> necessary information
> 
>    - it merges this new information with the contents of an existing
> database of the results of previous nesdoc runs
>      (this is what the current nesdoc does too, though the "database" is
> the HTML pages generated by the previous nesdoc runs - this merging
> should be easier with the more structured XML output from ncc)
> 
>    - a separate tool would take this XML database and generate HTML web
> pages, and whatever else we think is useful
> 
> Tasks
> -----
> 
> - updating nesC to generate the necessary information for nesdoc (I'll
> do that)
> - design of XML database, implementation of the merge with the XML
> output (VOLUNTEER NEEDED)
> - generate nice HTML web pages from the XML database (VOLUNTEER NEEDED)
> 
> David Gay
> 
> 
> 
> -------------------------------------------------------
> SF.Net email is Sponsored by the Better Software Conference & EXPO September
> 19-22, 2005 * San Francisco, CA * Development Lifecycle Practices
> Agile & Plan-Driven Development * Managing Projects & Teams * Testing & QA
> Security * Process Improvement & Measurement * http://www.sqe.com/bsce5sf
> _______________________________________________
> nescc-devel mailing list
> nescc-devel at lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/nescc-devel
>