"[MOSTLY SOLVED] Documenting an operator's parameters?"

daniel_thibault

How does one prevent the documentation from showing this in the GUI?

trace channel
Name of the trace channel to read.
Default value: metadata
Expert parameter
Depends on:
com.rapidminer.operator.io.CachedLTFExampleSource$1@15e672e7

My OperatorsDocMyOperator.xml has an operator element with sub-elements key, name, shortName, synopsis and help but I don't see in Unuk's resources/com.rapidminer.resources.i18n/OperatorsCoreDocumentation.xml how to cover the parameters' documentation.

MariusHelf

Hi,

the documentation for the parameters is displayed in the function getParameters(), where the parameters are actually specified. One of the parameters of the parameter creation functions is usually the description; other information is gathered implicitly, e.g. parameter type etc.

Best regards,
Marius

daniel_thibault

The ParameterType constructor and later methods only have a "short description" String. I'm trying to get rid of the "Depends on: com.rapidminer.operator.io.CachedLTFExampleSource$1@12015bce" part. I suppose this is related to the ParameterCondition object I create, but that constructor has no String description in it. How would you fix it?

MariusHelf

Is com.rapidminer.operator.io.CachedLTFExampleSource an ioobject that you created? Then you should document that object. In the RapidMiner core the ioobjects are documented in a file called ioobjects.xml in the resources folder. You can define the location of your extension's ioobjects file with a property in the build.xml, e.g.:

	<property name="extension.objectDefinition" value="/com/rapidminer/resources/ioobjectsMiA.xml" />

Happy coding!

daniel_thibault

Marius wrote:

Is com.rapidminer.operator.io.CachedLTFExampleSource an ioobject that you created? Then you should document that object. In the RapidMiner core the ioobjects are documented in a file called ioobjects.xml in the resources folder. You can define the location of your extension's ioobjects file with a property in the build.xml, e.g.: <property name="extension.objectDefinition" value="/com/rapidminer/resources/ioobjectsMiA.xml" />

No, CachedLTFExampleSource is an Operator, modelled after com.rapidminer.operator.io.CachedDatabaseExampleSource. Its io nature should therefore fall under "Data Table" (class="com.rapidminer.example.ExampleSet") io ioobjects.xml.  The operator itself is documented: com.rapidminer.resources.OperatorsLTFReader.xml has <operators name="LTFDataReader" version="5.0" docbundle="com/rapidminer/resources/i18n/OperatorsDocLTFReader"> and com.rapidminer.resources.i18n.OperatorsDocLTFReader.xml exists. Its <operator> element has <key>, <name>, <shortName>, <synopsis> and <help> sub-elements.

One operator parameter generated by getParameterTypes is PARAMETER_LTF_CHANNEL:

type = new ParameterTypeMutableStringCategory(PARAMETER_LTF_CHANNEL, 
            I18N.getMessage(I18N.getGUIBundle(), "gui.label.rmx_LTFDataReader.parameter.ltf_channel.description"),
            new String[] { "metadata" }, "metadata", false);
      type.registerDependencyCondition(isTraceCondition(this, PARAMETER_LTF_DIR));
      this.parameterTypes.add(type);

PARAMETER_LTF_CHANNEL has a dependency implemented by an inner class, which is probably what "com.rapidminer.operator.io.CachedLTFExampleSource$1@12015bce" is referring to.  Looking at descendants of ParameterCondition, I now see I need to override toString in order to achieve a proper rendering.  This should be made to appear in the Javadoc by overriding toString at the ParameterCondition level with a simple super(); call (currently toString only appears as an inherited method...all the way down from Object!).

I also note that the Javadoc of com.rapidminer.parameter.conditions.ParameterCondition completely omits getDefinitionAsXML(), which is a serious problem as this method is code-documented to state "Subclasses must override this method and...".

To sum up, I needed to build a proper ParameterCondition descendant and override its toString method to fix my issue.

MariusHelf

Hi,

thank you for your hints about missing javadoc documentation. We will the locations you mentioned.

Best regards,
Marius

MariusHelf

...on the other hand, #getDefinitionAsXML is already well-documented in the current svn version. Adding the #toString version seems to make sense, though.

Best!
Marius

daniel_thibault

Marius wrote:
...on the other hand, #getDefinitionAsXML is already well-documented in the current svn version. Adding the #toString version seems to make sense, though.

I was referring to http://rapid-i.com/api/rapidminer-5.1/index.html, which does not mention getDefinitionAsXML at all.

daniel_thibault

Any idea how I can get RapidMiner to invoke the (Element element) constructor of my ParameterCondition descendant? Also its getDefinitionAsXML and setOperator methods?  I'd like to debug them but can't seem to get them triggerred: I thought the save to repository and/or the "recent project" startup option would, but they don't.