[kepler-dev] Class Documentation Rework: Please update your ptII tree

[Christopher Brooks]

The executive summary: Please update your ptII tree.
I suggest doing a full clean because I removed a few classes, so try:

  ant full-clean ptolemy runkarlib run-dev

Details:
I folded Nandita's changes for the Documentation system into the
Ptolemy tree by creating a class called
ptolemy/vergil/actor/DocApplicationSpecializer.java

If the configuration contains a parameter called
_docApplicationSpecializer, then the parameter is assumed to name a
class implements DocApplicationSpecializer.  That interface declares a
method that reads a classname and returns a URL if the documentation
can be found.  The Kepler version look in $KEPLER_DOCS.

As a result, I was able to remove these duplicate classes from exp:
src/exp/ptolemy/vergil/basic/GetDocumentationAction and
src/exp/ptolemy/vergil/actor/{DocViewer,DocManager}

The Ptolemy version of these classes now offers the user the
possibility of accessing a website for the documentation.  Currently,
I'm using a URL on the Chess website that contains the Kepler actor
documentation.  Eventually, we should probably set up a directory
somewhere on the Kepler site with these documents.  This is not
something that needs to happen any time soon.  The location of
the remote documentation is controlled by the configuration.

The Ptolemy version of these classes also supports building the
documentation, though I have not yet configured this for Kepler.

Also, it appears that when I customize the documentation, then I lose
the initial documentation for the ports and parameters.  I'll have to
look in this.

I also added ant targets to build the Actor Index. More work need to
be done here as well. 

Also, running javadoc is showing some warnings because some classes in
exp are not being found.n


I'm not sure how to handle reviewing this code.  There is a tradeoff
between checking in unreviewed code and not checking in work pending
review that is rapidly getting out of date.  I think these changes
merit going in to the beta, because they work towards fixing a high
priority bug: duplicate classes in the exp directory.  The added
functionality of being able to get documentation from the website will
help casual developers who are building in kepler, but maybe not
keeping up with building in kepler-doc.

Comments?

_Christopher