[kepler-dev] Documentation display in Kepler
Nandita Mangal
nmangal at sdsc.edu
Thu May 25 12:04:47 PDT 2006
HI Christopher,
THanks for looking into the problem. I see some missing docs for some
actors..and will look into why
some actors are not getting javadocs created and keep you posted on
this. Otherwise it looks good!
thanks,
nandita.
Christopher Brooks wrote:
>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