[kepler-dev] Documentation display in Kepler

[Christopher Brooks]

Hi Dan
IMHO, this is wrong:
 numYPixels = new StringParameter(this, "Number of Y pixels in image")
it should be:
 numYPixels = new StringParameter(this, "numYPixels");

The name is not a description.  The name should be a Java identifier
and should match the parameter name.

This comes up for code gen for us.
Also, perhaps having names with spaces or arbitrary text could make
it difficult to refer to these parameters in expressions (not sure
about this).

I think we kicked this around on Kepler-dev awhile ago but did not
come up with a resolution.

StringParameter() takes two args
     *  @param container The container.
     *  @param name The name of the parameter.

I believe the StringParameter and Parameter documentation should be
much more clear about the name parameter.

We have tests in ptolemy/configs/test that look for ports and
parameters that have bogus names.

Comments?

That being said, maybe it is possible to hack the documentation display
to display something.

_Christopher



--------

    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 Documentation' the 
    result is
    
    "Number of Y pixels in image - No description"
    
    The code to display the xml file replaces the 'numYPixels' name 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 Scienc
   e Building - Room 3405
    Santa Barbara, CA 93195
    *******************************************************************
    
--------