Show Javadocs in Eclipse
Introduction
Javadocs help developers use third-party libraries. When a library is accompanied by its source codes, Eclipse shows documentation for classes and methods.
Unlike some open-source libraries, Amalgama Platform libraries are distributed in binary format only (jar files), with no source code attached. Amalgama Platform users can visit Javadoc section of this site anytime for API documentation.
To make Amalgama Platform usage more comfortable, we added JavaDocs inside Amalgama Platform jar files and created a plugin for Eclipse to extract those embedded JavaDocs.
Meet the 'showjavadoc' feature patch
The 'showjavadoc' is a so-called 'feature patch': when installed into Eclipse, it changes (replaces) a plugin that already exists in Eclipse. The plugin being replaced is the "org.eclipse.jdt.core" plugin that is part of the "org.eclipse.jdt" feature.
After the replacement, the (updated) "org.eclipse.jdt.core" plugin can look up the javadocs inside jars. A 'jar' file is an archive; Javadoc files are expected to be in the 'doc' top level folder of the jar file.
How to install
-
Launch Eclipse 2024-09
-
Open the
Help → Install New Software…dialog -
Enter the following URL:
https://nexus.am-sim.com/repository/showjavadoc/2024-09/ -
Unset the 'Group items by category' checkbox.
-
You should see the 'Showjavadoc' item. Select it and press 'Finish'.
-
If a 'Trust Artifacts' dialog pops up, select the only item in the top list and press 'Trust Selected'.
-
Confirm Eclipse restart.
Javadocs are now displayed
Create a new desktop application using the Desktop Application Wizard. Set its target as active and wait until the dependencies are downloaded.
Now, in the source codes of the generated desktop application, find the 'Model' class (in the …simulation bundle).
When the mouse cursor is hovered over the Engine class (part of the Amalgama Platform), its documentation is shown:
Javadocs are also displayed for class methods:
Eclipse’s code completion also shows JavaDocs:
