In order to understand documentation for Java APIs, it helps to have a context of some sort. As such, I created a simple little Java application to demonstrate how the various tags get rendered into the Javadoc.
The sample Java project is a little application about different tools that a coyote will use to capture a roadrunner. There are two classes (ACMESmartphone and Dynamite) and another class file called App that references the classes.
This program doesn’t really do anything except print little messages to the console, but it’s hopefully simple enough to be instructive in its purpose — to demonstrate different doc tags, their placement, and how they get rendered in the Javadoc.
One of your immediate challenges to editing Javadoc will be to get the source code into your IDE. The acmeproject is here on Github.
First clone the source using version control. We covered some version control basics earlier in the course.
You can clone the source in a couple of ways:
git clone https://github.com/tomjohnson1492/acmeproject
Or click Clone in Desktop and navigate to the right path in Github Desktop.
(If you don’t want to clone the source, you could click Download ZIP and download the content manually.)
Clear the Use default location check box, and then browse to where you cloned the Github project.
The Java files should be visible within your Eclipse IDE.
Java projects often have a lot of dependencies on packages that are third-party libraries or at least non-standard Java utilities. Rather than requiring users to download these additional packages and add them to their class manually, developers frequently use Maven to manage the packages.
Maven projects use a pom.xml file that defines the dependencies. Eclipse ships with Maven already installed, so when you import a Maven project and install it, the Eclipse Maven plugin will retrieve all of the project dependencies and add them to your project.
The sample project doesn’t use Maven, but I wanted to add a note about Maven here anyway because chances are if you’re getting a Java project from developers, you won’t import it in the way previously described. Instead, you’ll import it as an existing Maven project.
To import a Maven project into Eclipse:
Maven retrieves the necessary packages and builds the project. If the build is successful, you will see a “BUILD SUCCESS” message in the console. You then use the source code in the built project.
Get new posts delivered straight to your inbox.
© 2017, Tom Johnson