Difference between revisions of "EASE/Module Documentation"

Revision as of 07:37, 11 December 2019

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

 <JDK_location>\bin\javadoc.exe" -sourcepath <projectRoot>\src -root <projectRoot> -doclet org.eclipse.ease.helpgenerator.ModuleDoclet -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.ModuleDoclet</doclet>
 				<docletPath>${doclet.path}</docletPath>
 				<additionalparam>-root ${basedir} -failOnHTMLError true
 					-failOnMissingDocs true</additionalparam>
 
 				<useStandardDocletOptions>true</useStandardDocletOptions>
 				<offlineLinks>
 					<offlineLink>
 						<url>../../org.eclipse.platform.doc.isv/reference/api/</url>
 						<location>http://help.eclipse.org/oxygen/topic/org.eclipse.platform.doc.isv/reference/api</location>
 					</offlineLink>
 				</offlineLinks>
 			</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

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()}