[kepler-dev] Request for adding documentation on Kepler Actors

[Matt Jones]

No.  We've considered this carefully over the course of several Kepler 
meetings. We also did an experiment with doclets in a previous release 
(which is currently not working because Sun broke their doclet code in 
JDK 1.5), and determined the format is not optimal for our needs.

In addition, this is user documentation, not developer documentation, 
and will need to be edited on a different cycle and by different people 
than the source code.  So we feel it is better to not tie it to 
revisions of the java files.  In addition, we need to be able to include 
both natural language documentation and machine-readable documentation 
in the form of OWL-DL statements.  So we decided that it was best to 
group both of these types of documentation within the MoML description 
of an actor.  As a result, the documentation can still be used in many 
contexts as can doclets (ie, context sensitive help and html user manuals).

Finally, we need the same documentation for composite actors and 
specialized atomic actors that we do for generic atomic actors, and so 
the java code is not an option here (because composites don't have any 
java code that is relevant to the specialized actor, and specialized 
atomic actors can not be documented in the more generic java code).  As 
a result, we decided it was best to use the MoML document which is 
common to both composite and atomic actors to house the documentation.

Matt

Edward A. Lee wrote:
> Wouldn't it be better to automatically generate the documentation
> information using a doclet?
> 
> Edward
> 
> At 05:08 PM 11/30/2005 -0800, nmangal at sdsc.edu wrote:
> 
>>Hello Kepler-Developers,
>>
>>For implementing Kepler documentation framework, we have implemented xslt
>>processors which based on actorList.moml and
>>actor kar files produce respective html MAN pages for all kepler actors.
>>However the current MAN pages ,which are
>>similar to javadoc in formatting , are currently lacking the main
>>function/purpose of the actor and authors etc.
>>
>>I request all Kepler developers to kindly add the above information in 3-4
>>lines on their respective actor's entities , to help the Kepler MAN pages
>>be
>>even more helpful for Kepler users and beginners. We are trying to
>>incorporate the above MAN pages for the upcoming Kepler release.
>>
>>Kindly follow the following steps to add documentation to your actor MAN
>>pages:
>>
>>1) Get an CVS updated version of actorList.moml
>>   (configs\ptolemy\configs\kepler)
>>2) For each actor entity that you have recently developed or in the past
>>add the following XML information
>>   under the "documentation" property
>>
>>   Sample Constant Actor Entity Documentation:
>>
>>    <!-- Documentation regarding the actor's overall functionality. -->
>>  <property name="documentation"
>>class="org.kepler.moml.DocumentationAttribute">
>>    <configure>
>>    <description><brief>Produces a constant value on each fire
>>cycle.</brief>  The constant value is set by the user as
>>                 a parameter of the actor, or defaults to an integer value
>>of 1 if unset.
>>    </description>
>>    <algorithm>Examines the &quot;value&quot; parameter and emits it on
>>the ouput port during each fire event.</algorithm>
>>    <typicalUsage>Used to parameterize other models that take constant
>>values as inputs.</typicalUsage>
>>    <author>Yuhong Xiong</author>
>>    <author>Edward A. Lee</author>
>>    <project>Ptolemy II</project>
>>    </configure>
>>  </property>
>>
>>
>>3) Build the KSW library , Kepler to make sure there was so invalid
>>XML/other errors.
>>4) Check in the actorList.moml files into CVS.
>>
>>You are free to add additional nodes under the root configure node to
>>further describe your actor.
>>If you have any further questions please feel free to email me at
>>nmangal at sdsc.edu
>>
>>Thank you for your co-operation.
>>Sincerely,
>>Nandita Mangal.
>>
>>
>>_______________________________________________
>>Kepler-dev mailing list
>>Kepler-dev at ecoinformatics.org
>>http://mercury.nceas.ucsb.edu/ecoinformatics/mailman/listinfo/kepler-dev
> 
> 
> ------------
> 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  
> 
> _______________________________________________
> Kepler-dev mailing list
> Kepler-dev at ecoinformatics.org
> http://mercury.nceas.ucsb.edu/ecoinformatics/mailman/listinfo/kepler-dev

-- 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Matt Jones                                   Ph: 907-789-0496
jones at nceas.ucsb.edu                    SIP #: 1-747-626-7082
National Center for Ecological Analysis and Synthesis (NCEAS)
UC Santa Barbara     http://www.nceas.ucsb.edu/ecoinformatics
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~