[kepler-dev] Documentation display in Kepler
Christopher Brooks
cxh at eecs.berkeley.edu
Tue May 23 17:38:10 PDT 2006
Hi Nandita,
Ok, I figured out the problem I was having and (oddly) solved it.
The docs are now properly being generated. I cleaned up the
build.xml file so that the indentation was more consistent for
the generateDoc targets. I also increased the amount of memory
for docCheck so the docCheck will complete for me on one
of the Windows boxes I use.
We now have one version of PtDoc, the version in $PTII/doc/doclets,
which generates output in a different directory if the KEPLER
property is set. We could try using a command line argument
here instead, but I left that for next time.
It looks like running "ant generateDoc" updates files
in kepler-docs/dev/documentationFramework that are also checked
in to CVS. I'll update those files momentarily.
The primary change is that the documentation for the Expression
actor now include documentation for the expression StringAttribute.
Other classes that have public StringAttributes now also have
documentation for those StringAttributes.
Also, I'll be on vacation Wednesday afternoon through Tuesday . .
_Christopher
--------
Hi Nandita,
I've attempted to fix a problem with PtDoclet, where
the expression StringParameter of the Expression Actor
was not ending up the documentation. In the process
of fixing this, I noticed kepler/doc/doclets/PtDoclet.java,
which is a copy of ptII/doc/doclets/PtDoclet.java
Initially I thought that the kepler version was being
used, but when I look at how "ant generateDoc" works,
it looks like it is not being used? It's not
very clear to me how the build works, I can see
that javadoc is run on the Kepler files and then
the xsl transformations are run.
I also fixed problems where generateDoc was running
out of memory and not finding classes in exp/ptolemy.
If you have a chance, can you do an update of
the ptII and kepler trees and verify that
"ant generateDoc" does what it should?
I'll keep checking as well.
Thanks,
Christopher
------- Forwarded Message
From: "Christopher Brooks" <cxh at eecs.berkeley.edu>
To: "Edward A. Lee" <eal at eecs.berkeley.edu>
Subject: Re: [kepler-dev] Documentation display in Kepler
Cc: Kepler-dev at ecoinformatics.org
Date: Mon, 22 May 2006 20:31:08 -0700
Also, I modified PtDoclet.java so that it looks for StringAttributes
fields and displays those as parameters. The reason is that
the Expression actor has a StringParameter public field named
"expression" and the Doclet was not displaying the documentation.
I thought that there was something up with customizing documentation,
but this was the problem.
Kepler has a copy of PtDoclet.java, I'll see about merging the two
copies.
_Christopher
- --------
I have (finally) checked in the fix for this.
Documentation displays now show the display name for ports and paramete
rs.
Edward
At 03:35 PM 5/5/2006, Edward A. Lee wrote:
>Oh, sorry... I misunderstood... Indeed, the documentation system
>doesn't do the right thing... I'll fix it...
>
>Edward
>
>At 02:10 PM 5/5/2006, Nandita Mangal wrote:
>>Hi All,
>>I haven't changed the way port name are displayed in documentation
>>system in kepler in docViewer...Is there
>>any other place kepler port name settings might be set?
>>thanks,
>>nandita.
>>
>>
>>Edward A. Lee wrote:
>>
>>>Hmm... Works for me... Perhaps Kepler changes the way port names
>>>are displayed?
>>>
>>>Edward
>>>
>>>At 12:25 AM 5/5/2006, Zhijie Guan wrote:
>>>
>>>
>>>>Hi Edward,
>>>>
>>>>Thanks for adding setDisplayName() to NamedObj. I like this feature
.
>>>>
>>>>I have tried this method in my code. But unfortunately the Display
>>>>Name cannot be displayed with the port, instead, the port's name is
>>>>still displayed.
>>>>
>>>>For example, in the Actor/CIPRes/Initializer actor, I used the
>>>>following code to set a different display name:
>>>>
>>>> // construct the output port outputTrigger
>>>> outputTrigger= new TypedIOPort(this, "outputTrigger", false
,
>>>>true);
>>>> outputTrigger.setDisplayName("Trigger");
>>>>
>>>>When I run this actor and configure the port "outputTrigger" to sho
w
>>>>its name, the port name "outputTrigger" is shown instead of the
>>>>display name "Trigger".
>>>>
>>>>I guess it is because the code for displaying DisplayName is not
>>>>changed yet. Could you please guide me where I should look for thes
e
>>>>code? I think since now we have DisplayName for all the NamedObj, w
e
>>>>need to change the displaying code in multiple places.
>>>>
>>>>Zhijie
>>>>
>>>>
>>>>
>>>>On May 4, 2006, at 11:20 AM, Edward A. Lee wrote:
>>>>
>>>>
>>>>
>>>>>I have implemented setDisplayName() for ports...
>>>>>
>>>>>Actually, I promoted it to all NamedObj, which is essentially
>>>>>everything. So now, every object in Ptolemy II can have a differen
t
>>>>>display name from its name in the hieararchy.
>>>>>
>>>>>Edward
>>>>>
>>>>>
>>>>>At 12:10 PM 4/25/2006, Edward A. Lee wrote:
>>>>>
>>>>>
>>>>>
>>>>>>This is not implemented for ports...
>>>>>>It could be, though... It's a good idea...
>>>>>>I'll look into it...
>>>>>>
>>>>>>Edward
>>>>>>
>>>>>>At 05:46 PM 4/24/2006, Zhijie Guan wrote:
>>>>>>
>>>>>>
>>>>>>>Hi Edward,
>>>>>>>
>>>>>>>Do we have a similar function to set the display name of a port,
>>>>>>like
>>>>>>
>>>>>>
>>>>>>>TypedIOPort?
>>>>>>>
>>>>>>>I finally figured out by reading the source code that the
>>>>>>>setDisplayName() function is implemented in
>>>>>>AbstractSettableAttribute
>>>>>>
>>>>>>
>>>>>>>class. But I did not see the function definition in the JavaDoc
of
>>>>>>>that class. I use the JavaDoc of ptII5.0.1 at http://
>>>>>>>ptolemy.eecs.berkeley.edu/ptolemyII/ptII5.0/ptII5.0.1/doc/codeDo
c/
>>>>>>>ptolemy/kernel/util/AbstractSettableAttribute.html
>>>>>>>
>>>>>>>Do we have a newer JavaDoc for ptII?
>>>>>>>
>>>>>>>Thanks!
>>>>>>>
>>>>>>>Zhijie
>>>>>>>
>>>>>>>
>>>>>>>On Mar 14, 2006, at 5:24 PM, Edward A. Lee wrote:
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>>Dan:
>>>>>>>>
>>>>>>>>The code you give isn't right... The statement:
>>>>>>>>
>>>>>>>> numYPixels = new StringParameter(this, "Number of Y pixels
in
>>>>>>>>image");
>>>>>>>>
>>>>>>>>is not setting the display name to "Number of Y pixels in image
",
>>>>>>>>but rather is creating a new parameter named "Number of Y pixel
s in
>>>>>>>>image".
>>>>>>>>The right way to set the display name is:
>>>>>>>>
>>>>>>>> numYPixels = new StringParameter(this, "numYPixels");
>>>>>>>> numYPixels.setDisplayName("Number of Y pixels in image");
>>>>>>>>
>>>>>>>>Note that the former code violates our coding standards, and as
>>>>>>>>a consequence, the actor will not clone correctly. After the
>>>>>>clone()
>>>>>>
>>>>>>
>>>>>>>>operation, the numYPixels field of the new actor will actually
be a
>>>>>>>>reference to the numYPixels parameter of the original actor.
>>>>>>That is,
>>>>>>
>>>>>>
>>>>>>>>both actors will refer to the same parameter. If you insist on
>>>>>>having
>>>>>>
>>>>>>
>>>>>>>>a field name different from the parameter name, then you should
>>>>>>>>override
>>>>>>>>the clone(Workspace) method to correctly set the field of the
>>>>>>clone.
>>>>>>
>>>>>>
>>>>>>>>That said, I'm not sure whether the documentation infrastructur
e is
>>>>>>>>properly reflecting the possible distinction between the parame
ter
>>>>>>>>name and the display name. There may be an actual bug there...
>>>>>>>>
>>>>>>>>Edward
>>>>>>>>
>>>>>>>>
>>>>>>>>At 02:26 PM 3/14/2006, Dan Higgins wrote:
>>>>>>>>
>>>>>>>>
>>>>>>>>>Hi All,
>>>>>>>>>
>>>>>>>>> In adding documentation to the RExpression actor, I
>>>>>>discoved a
>>>>>>
>>>>>>
>>>>>>>>>problem with the documentation display in Kepler (and perhaps
in
>>>>>>>>>Ptolemy, also).
>>>>>>>>>
>>>>>>>>>Consider one parameter defined in the RExpression actor -
>>>>>>>>>
>>>>>>>>> /**
>>>>>>>>> * The height of the output graphics bitmap in pixels
>>>>>>>>> */
>>>>>>>>> public StringParameter numYPixels;
>>>>>>>>>
>>>>>>>>>But later on, this parameter is created with the statement
>>>>>>>>>
>>>>>>>>> numYPixels = new StringParameter(this, "Number of Y
>>>>>>pixels in
>>>>>>
>>>>>>
>>>>>>>>>image");
>>>>>>>>>
>>>>>>>>>Note that the display string "Number of Y pixels in image" is
>>>>>>not the
>>>>>>
>>>>>>
>>>>>>>>>same as the varible name 'numYPixels'
>>>>>>>>>
>>>>>>>>>The doclet generated xml file has the proper association
>>>>>>between the
>>>>>>
>>>>>>
>>>>>>>>>property and value; i.e.
>>>>>>>>>
>>>>>>>>><property name="numYPixels">The height of the output graphics
>>>>>>>>>bitmap in
>>>>>>>>>pixels</property>
>>>>>>>>>
>>>>>>>>>But when I display the doc xml in Kepler using 'Get Documentat
ion'
>>>>>>>>>the
>>>>>>>>>result is
>>>>>>>>>
>>>>>>>>>"Number of Y pixels in image - No description"
>>>>>>>>>
>>>>>>>>>The code to display the xml file replaces the 'numYPixels' nam
e
>>>>>>>>>with its
>>>>>>>>>display string 'Number of Y pixels in image' but it then loses
the
>>>>>>>>>value! This seems to happen whenever the parameter name is
>>>>>>different
>>>>>>
>>>>>>
>>>>>>>>>than the display string; when they agree, the descriptions are
>>>>>>shown
>>>>>>
>>>>>>
>>>>>>>>>properly.
>>>>>>>>>
>>>>>>>>>Dan
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>--
>>>>>>>>>**************************************************************
****
*
>>>>>>>>>Dan Higgins
>>>>>>higgins at nceas.ucsb.edu
>>>>>>
>>>>>>
>>>>>>>>>http://www.nceas.ucsb.edu/ Ph: 805-893-5127
>>>>>>>>>National Center for Ecological Analysis and Synthesis (NCEAS)
>>>>>>Marine
>>>>>>
>>>>>>
>>>>>>>>>Science Building - Room 3405
>>>>>>>>>Santa Barbara, CA 93195
>>>>>>>>>**************************************************************
****
*
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>_______________________________________________
>>>>>>>>>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
>>>>>>
>>>>>>------------
>>>>>>Edward A. Lee
>>>>>>Professor, Chair of the EE Division, Associate Chair of EECS
>>>>>>231 Cory Hall, UC Berkeley, Berkeley, CA 94720-1770
>>>>>>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/ ke
pler
-dev
>>>>>------------
>>>>>Edward A. Lee
>>>>>Professor, Chair of the EE Division, Associate Chair of EECS
>>>>>231 Cory Hall, UC Berkeley, Berkeley, CA 94720-1770
>>>>>phone: 510-642-0253 or 510-642-0455, fax: 510-642-2845
>>>>>eal at eecs.Berkeley.EDU, http://ptolemy.eecs.berkeley.edu/~eal
>>>
>>>------------
>>>Edward A. Lee
>>>Professor, Chair of the EE Division, Associate Chair of EECS
>>>231 Cory Hall, UC Berkeley, Berkeley, CA 94720-1770
>>>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
>
>------------
>Edward A. Lee
>Professor, Chair of the EE Division, Associate Chair of EECS
>231 Cory Hall, UC Berkeley, Berkeley, CA 94720-1770
>phone: 510-642-0253 or 510-642-0455, fax: 510-642-2845
>eal at eecs.Berkeley.EDU, http://ptolemy.eecs.berkeley.edu/~eal
------------
Edward A. Lee
Professor, Chair of the EE Division, Associate Chair of EECS
231 Cory Hall, UC Berkeley, Berkeley, CA 94720-1770
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-de
v
- --------
_______________________________________________
Kepler-dev mailing list
Kepler-dev at ecoinformatics.org
http://mercury.nceas.ucsb.edu/ecoinformatics/mailman/listinfo/kepler-dev
------- End of Forwarded Message
_______________________________________________
Kepler-dev mailing list
Kepler-dev at ecoinformatics.org
http://mercury.nceas.ucsb.edu/ecoinformatics/mailman/listinfo/kepler-dev
--------
More information about the Kepler-dev
mailing list