[kepler-dev] Documentation updates

[Edward A. Lee]

At 10:55 AM 1/6/2006 -0600, Kevin Ruland wrote:

>Edward,
>
>You have thought of everything.  It seems that there should be no 
>difficulty here.  I do have some questions:  The DocML file, is it a 
>seperate file or is it embedded in the actor's moml file?  Is it possible 
>to call the rendering tool using an open InputStream rather than a 
>filename?  This will enable us to track down the DocML file using 
>ClassLoader.getResourceAsStream().

The DocML file is a separate file.
It is opened using exactly the same mechanism that is used to open
any file from Vergil, so you can open it via the File menu, via a hyperlink,
or via the "Get Documentation" context menu, and all three yield the same
display of the docs.

When you override docs in an instance, the information is not stored
in DocML at all, but rather as an instance of DocAttribute, which contains
one attribute corresponding to each DocML element.  This neatly avoids
the problem of trying to nest two distinct DTDs within one XML file.


>BTW - I do have to agree that well written class documentation is useful 
>to both developers and users.  My experience with reading and writing 
>javadoc is it tends to be quite brief and sometimes very confusing.
>Let's hope at least this piece of javadoc can be well written.


I agree... Hopefully making the docs more visible this way will encourage
actor developers to create decent docs.  E.g., right now, it is very
obvious if no documentation is given for a port or parameter...

Edward


------------
Edward A. Lee
Professor, Chair of the EE Division, Associate Chair of EECS
231 Cory Hall, UC Berkeley, Berkeley, CA 94720
phone: 510-642-0253 or 510-642-0455, fax: 510-642-2845
eal at eecs.Berkeley.EDU, http://ptolemy.eecs.berkeley.edu/~eal