Project

General

Profile

Bug #5529

Documentation for some actors such as Run Composite Actor is empty

Added by Christopher Brooks over 7 years ago. Updated almost 7 years ago.

Status:
Resolved
Priority:
Normal
Assignee:
Category:
documentation
Target version:
Start date:
10/31/2011
Due date:
% Done:

0%

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/";
}

History

#1 Updated by Daniel Crawl over 7 years ago

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

#2 Updated by Christopher Brooks over 7 years ago

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

#3 Updated by Daniel Crawl over 7 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.

#4 Updated by Christopher Brooks over 7 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.

#5 Updated by Daniel Crawl over 7 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.

#6 Updated by Daniel Crawl over 7 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.

#7 Updated by Christopher Brooks over 7 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?

#8 Updated by Daniel Crawl almost 7 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?

#9 Updated by Christopher Brooks almost 7 years ago

Daniel, this bug looks fixed (thanks), so I'm closing it.

#10 Updated by Redmine Admin over 6 years ago

Original Bugzilla ID was 5529

Also available in: Atom PDF