Bug #5529: Documentation for some actors such as Run Composite Actor is empty - Kepler - Ecoinformatics Redmine

Actions

Copy link

Bug #5529

closed

Documentation for some actors such as Run Composite Actor is empty

Added by Christopher Brooks about 13 years ago. Updated over 12 years ago.

Status:

Resolved

Priority:

Normal

Assignee:

Daniel Crawl

Category:

documentation

Target version:

2.4.0

Start date:

10/31/2011

Due date:

% Done:

Estimated time:

Bugzilla-Id:

5529

Description

In the devel trunk and in Kepler-2.2, the documentation for Run Composite Actor
is empty.

To replicate:
1) Start Kepler
2) Search for
Run Composite Actor
3) Drag the actor on to the canvas
4) Right click and select Documentation -> Display

However, documentation for actors like Constant are present.

My guess is that
kepler/actors/resources/kar/CoreActors/RunCompositeActor.xml
has no actor-specific documentation

There are several bugs here:
1) The file has no real documentation. I updated that file with documentation,
but my changes do not appear when I try to view the documentation? Why?

2) There is no obvious way to update the file. When I get a mostly empty
file, I should at least get link to instructions about how to update
the docs. There are some docs at
https://kepler-project.org/developers/reference/updating-the-kepler-directors-and-actors

3) There are probably a bunch of other actors that have very minimal documentation.

These actors have documentation that is 17 lines or less:

bash-3.2$ wc -l ~/src/kepler/actors/resources/kar/CoreActors/*.xml | sort -nr | tail -15
17 /Users/cxh/src/kepler/actors/resources/kar/CoreActors/NexusFileReader.xml
16 /Users/cxh/src/kepler/actors/resources/kar/CoreActors/TreeToString.xml
16 /Users/cxh/src/kepler/actors/resources/kar/CoreActors/Image.xml
15 /Users/cxh/src/kepler/actors/resources/kar/CoreActors/SequenceScope.xml
15 /Users/cxh/src/kepler/actors/resources/kar/CoreActors/MemeOpalInput.xml
15 /Users/cxh/src/kepler/actors/resources/kar/CoreActors/Logger.xml
15 /Users/cxh/src/kepler/actors/resources/kar/CoreActors/HistogramPlotter.xml
14 /Users/cxh/src/kepler/actors/resources/kar/CoreActors/MastOpalInput.xml
10 /Users/cxh/src/kepler/actors/resources/kar/CoreActors/IntRangeParameter.xml
10 /Users/cxh/src/kepler/actors/resources/kar/CoreActors/Documentation.xml
9 /Users/cxh/src/kepler/actors/resources/kar/CoreActors/RunCompositeActor.xml
9 /Users/cxh/src/kepler/actors/resources/kar/CoreActors/PAUPConsensusTrees.xml
9 /Users/cxh/src/kepler/actors/resources/kar/CoreActors/JRunCIPRes.xml
9 /Users/cxh/src/kepler/actors/resources/kar/CoreActors/ClustalWSeqAlign.xml
9 /Users/cxh/src/kepler/actors/resources/kar/CoreActors/AlignmentEditor_Seaview.xml

It would be best if the documentation would default to the Ptolemy documentation, or at least if there was a link. In vergil, if there
is no documentation found, then the user is offered a link to documentation
at http://ptolemy.eecs.berkeley.edu/ptolemyII/ptII8.1/ptII.
The way this works is that the major version number is used.
See vergil/basic/GetDocumentationAction.java:

Parameter remoteDocumentationURLBaseParameter = (Parameter) configuration
                        .getAttribute("_remoteDocumentationURLBase",
                                Parameter.class);
                String tentativeRemoteDocumentationURLBase = null;
                if (remoteDocumentationURLBaseParameter != null) {
                    tentativeRemoteDocumentationURLBase = remoteDocumentationURLBaseParameter
                            .getExpression();
                } else {
                    tentativeRemoteDocumentationURLBase = "http://ptolemy.eecs.berkeley.edu/ptolemyII/ptII" 
                            + VersionAttribute.majorCurrentVersion() + "/ptII/";
                }

Actions

Copy link

Updated by Daniel Crawl about 13 years ago

For the first bug: in my experience, changes to the actor metadata file do not appear in Kepler unless .kepler is removed.

Actions

Copy link

Updated by Christopher Brooks about 13 years ago

Daniel suggested removing ~/.kepler to regenerate the docs. The docs are still empty for me after removing ~/.kepler.

Actions

Copy link

Updated by Daniel Crawl about 13 years ago

The userLevelDocumentation property must be enclosed by the KeplerDocumentation property. I fixed this in RunCompositeActor.xml, and, after removing ~/.kepler, the documentation appears in the actor.

Actions

Copy link

Updated by Christopher Brooks about 13 years ago

Thanks, I now get the Run Composite Actor documentation. There should be a bug report for the problem where userLevelDocumentation is not enclosed by the KeplerDocumentation. This seemed to fail silently, I was given no clue as to the problem.

Actions

Copy link

Updated by Daniel Crawl about 13 years ago

I've updated the KARCacheManager to reload KARs if their modified time is different than when they were loaded into the cache. Now when an actor's documentation is updated in the XML file, the changes will appear in Kepler.

Actions

Copy link

Updated by Daniel Crawl about 13 years ago

I've updated KeplerMetadataExtractor to display a warning when userLevelDocumentation is not enclosed by a KeplerDocumentation. If you set the log4j log level to debug, it also prints which actors are missing documentation:

Add Point To SVG is missing userLevelDocumentation and author documentation.
AlignmentEditor(Seaview) KeplerDocumentation is empty.
Anyof Parameter is missing userLevelDocumentation and author documentation.
Archive Counter is missing userLevelDocumentation and author documentation.
Array Append is missing userLevelDocumentation and author documentation.
ClustalWSeqAlign KeplerDocumentation is empty.
Copy From Node is missing userLevelDocumentation and author documentation.
Copy To Node is missing userLevelDocumentation and author documentation.
Create Expression From Query is missing userLevelDocumentation and author documentation.
Create Request From Result is missing userLevelDocumentation and author documentation.
Documentation is missing userLevelDocumentation and author documentation.
End Plan File is missing userLevelDocumentation and author documentation.
Execute On Node is missing userLevelDocumentation and author documentation.
GAMESS Plan File Generator is missing userLevelDocumentation and author documentation.
Histogram Plotter is missing userLevelDocumentation and author documentation.
IntRangeParameter is missing userLevelDocumentation and author documentation.
JRunCIPRes KeplerDocumentation is empty.
Logger is missing userLevelDocumentation and author documentation.
MappedLogger is missing userLevelDocumentation and author documentation.
MastOpalInput is missing KeplerDocumentation.
MemeOpalInput is missing userLevelDocumentation and author documentation.
On Error is missing userLevelDocumentation and author documentation.
Oneof Parameter is missing userLevelDocumentation and author documentation.
PAUPConsensusTrees KeplerDocumentation is empty.
Parameter is missing userLevelDocumentation and author documentation.
Random Parameter is missing userLevelDocumentation and author documentation.
Range Points Parameter is missing userLevelDocumentation and author documentation.
Range Step Parameter is missing userLevelDocumentation and author documentation.
SRB Add Metadata is missing userLevelDocumentation and author documentation.
SRB SPut is missing userLevelDocumentation and author documentation.
SRB Stream Put is missing userLevelDocumentation and author documentation.
SemanticTypeParameter is missing userLevelDocumentation and author documentation.
Sequence Scope is missing userLevelDocumentation and author documentation.
Server Execute is missing userLevelDocumentation and author documentation.
Single Parameter is missing userLevelDocumentation and author documentation.
Sleep is missing userLevelDocumentation and author documentation.
Start Plan File is missing userLevelDocumentation and author documentation.
Substitute is missing userLevelDocumentation and author documentation.
SyncOnTerminator is missing userLevelDocumentation and author documentation.
Temp Actor is missing userLevelDocumentation and author documentation.
Triggered Enum Item is missing userLevelDocumentation and author documentation.

I'm working on automatically generating the documentation for these using the Kepler doclet.

Actions

Copy link

Updated by Christopher Brooks about 13 years ago

It is good that we are making progress on this, see also
http://bugzilla.ecoinformatics.org/show_bug.cgi?id=4909
Actor documentation: updates ignored, duplicate info, how to refer to other actors/models?

Actions

Copy link

Updated by Daniel Crawl over 12 years ago

I added documentation based on the javadocs to:

AddPointToSVG.xml
AlignmentEditor_Seaview.xml
ArchiveCounter.xml
ArrayAppend.xml
ClustalWSeqAlign.xml
CreateExpressionFromQuery.xml
CreateRequestFromResult.xml
Documentation.xml
HistogramPlotter.xml
IntRangeParameter.xml
JRunCIPRes.xml
Logger.xml
MappedLogger.xml
MastOpalInput.xml
MemeOpalInput.xml
PAUPConsensusTrees.xml
Parameter.xml
SRBAddMetadata.xml
SRBSPut.xml
SRBStreamPut.xml
SemanticTypeParameter.xml
SequenceScope.xml
ServerExecute.xml
Sleep.xml
SyncOnTerminator.xml
TempActor.xml
TriggeredEnumItem.xml

The remaining actors missing documentation all appear to be composite actors in actors/src/org/resurgence/moml:

Anyof Parameter
Copy From Node
Copy To Node
End Plan File
Execute On Node
GAMESS Plan File Generator
On Error
Oneof
Random Parameter
Range Points Parameter
Range Step Parameter
Single Parameter
Start Plan File
Substitute

Christopher, what's left for this bug for 2.4?

Actions

Copy link