EASE/Module Documentation

Module Documentation

Module documentation needs to be provided as eclipse help files in the same plugin as the module implementation. Creation of such files by hand is not recommended and also not documented. Instead EASE provides a doclet that can be used with the javadoc tool to create such files either manually or fully integrated within a tycho build.

Prerequisites

The doclet is built nightly and can be downloaded from our jenkins server.

Your class documentation needs to be well formed. Default javaDoc html files do accept XML errors like missing closing tags or unescaped HTML entities like '<' or '>' as part of the plain text. EASE does not, as it uses an XML parser to read these html files. So make sure your comments are clean. The doclet will run tests on the output to make sure we do not store invalid xml files.

Your extension point ID for the module needs to follow the naming scheme: <pluginId>.<moduleId_without_any_further_dots>. If this is not the case, linking between modules will not work correctly.

Run the doclet manually

Run for Java 8 or older:

 <JDK8_location>\bin\javadoc.exe" -sourcepath <projectRoot>\src -root <projectRoot> -doclet org.eclipse.ease.helpgenerator.V8ModuleDoclet -docletpath ease.module.doclet.jar -failOnHTMLError true -failOnMissingDocs true -link https://docs.oracle.com/javase/8/docs/api <package_names_to_look_for_classes>

Run for Java 9 or newer:

 <JDK9_location>\bin\javadoc.exe" -sourcepath <projectRoot>\src -root <projectRoot> -doclet org.eclipse.ease.helpgenerator.V9ModuleDoclet -docletpath ease.module.doclet.jar -failOnHTMLError true -failOnMissingDocs true -link https://docs.oracle.com/javase/8/docs/api <package_names_to_look_for_classes>

Run the doclet from maven

 <build>
 	<plugins>
 		<plugin>
 			<artifactId>maven-javadoc-plugin</artifactId>
 			<groupId>org.apache.maven.plugins</groupId>
 			<version>${maven.javadoc.version}</version> 
 			<configuration>
 				<outputDirectory>${project.build.directory}/../mydocs</outputDirectory>
 				<doclet>org.eclipse.ease.helpgenerator.V9ModuleDoclet</doclet>
 				<docletPath>${doclet.path}</docletPath>
 				<additionalparam>-root ${basedir}
 					-encoding 'UTF-8'
 					-failOnHTMLError true
 					-failOnMissingDocs true
 					-link
 						https://docs.oracle.com/en/java/javase/11/docs/api
 					-linkoffline
 						../../org.eclipse.platform.doc.isv/reference/api/
 						http://help.eclipse.org/oxygen/topic/org.eclipse.platform.doc.isv/reference/api
 				</additionalparam>
 				<additionalOptions>-root ${basedir}
 					-encoding 'UTF-8'
 					-failOnHTMLError true
 					-failOnMissingDocs true
 					-link
 						https://docs.oracle.com/en/java/javase/11/docs/api
 					-linkoffline
 						../../org.eclipse.platform.doc.isv/reference/api/
 						http://help.eclipse.org/oxygen/topic/org.eclipse.platform.doc.isv/reference/api
 					-linkoffline
 						../../org.eclipse.ease.help/help/api-docs/javadoc/
 						https://ci.eclipse.org/ease/job/ease.build.core/JavaDoc
 				</additionalOptions>
 					<useStandardDocletOptions>false</useStandardDocletOptions>
 			</configuration>
 			<executions>
 				<execution>
 					<id>build-docs</id>
 					<phase>generate-resources</phase>
 					<goals>
 						<goal>javadoc</goal>
 					</goals>
 				</execution>
 			</executions>
 		</plugin>
 
 		<plugin>
 			<artifactId>build-helper-maven-plugin</artifactId>
 			<groupId>org.codehaus.mojo</groupId>
 			<version>${maven.buildhelper.version}</version>
 			<executions>
 				<execution>
 					<id>add_help</id>
 					<phase>generate-resources</phase>
 					<goals>
 						<goal>add-resource</goal>
 					</goals>
 					<configuration>
 						<resources>
 							<resource>
 								<directory>${basedir}/help</directory>
 								<targetPath>help</targetPath>
 							</resource>
 						</resources>
 					</configuration>
 				</execution>
 			</executions>
 		</plugin>
 	</plugins>
 </build>
 

${doclet.path} needs to be set correctly to the location of the doclet.jar

Make sure to select the right doclet V8ModuleDoclet or V9ModuleDoclet depending on your java version.

• -failOnHTMLError: forces comments to be valid HTML code. This is required for inline help display as this is based on an XML parser which requires valid encoding
• -failOnMissingDocs: requires each module/method/parameter/return type/exception to be documented. Recommended as users expect full documentation on methods
• -link/-linkoffline: create documentation links to java classes. Same syntax as the standard java doclet provides.

Documentation links

Links to classic javadoc files, eg {@link Collection#toString()} will automatically be resolved correctly. However the current doclet implementation will always create links for documenation created with java9 or lower. Form Java10 onwards the style of HTML pages changed, therefore links will not work correctly anymore.

You may also link to other module descriptions or methods within the same module. Therefore use

• {@module #methodName()}
• {@module #fieldName}
• {@module module.id.of.target.module#methodName()}

Documenting examples

To provide examples of method calls you may use the @scriptExample annotation in comments:

 /**
  * @scriptExample thisIsYourCall("with", "some", "parameters") ... and this is the description
  * @scriptExample thisIsYourCall("with", "other", "parameters") ... some changed behavior
  */

This type of examples is useful for simple showcases of a function call. They do not work for complex or multiline statements. Best use '...' to separate code from description. If this token cannot be found we try to find the end of the function call by counting closing brackets.