This tutorial introduces the Javadoc documentation distributed as part of the FRC Java plugins. Understanding how to use the documentation properly is critical for successful programming.
EDIT - 1/2017: This article was originally written for the 2013 season, This was before eclipse was the default IDE supported by wpilib. There is now an official plugin for eclipse and instructions for setup maintained at the wpilib screenstepslive webpage. That said, we still maintain an up-to-date copy of the javadocs on our domain, as well as archived revisions for reference. WPILIB javadocs: current (2017), 2016, 2015, 2014, 2013. Why do we bother hosting these? Our copies of the javadocs include links to the source code. Just click on any method name within the javadoc and wou will be brought to the implementation. This is helpful if/when you find the librarie's javadoc comments to be lacking specific implementation details, or when you're tryign to investigate anomolous behaviour.
If you're going to be programming with Java you're going to want to get familiar with all the tools that are available out of the box. If you've followed the guide for setting up the Java environment for the FIRST Robotics Competition, you've already got all the documentation available to you.
Do you know where it is?
The 2013 Java documentation gets installed in a directory within your user profile by default. You should be able to find it at: %USERPROFILE%\sunspotfrcsdk\doc\javadoc
We alo provide a mirror of the 2013 javadocs here: http://team2168.org/javadoc
Opening the index.html file will bring up a browser navigable listing of all the documentation for the FRC Java API. If you're familiar with Java, this documentation format will be immediately recognizable as being created with the Javadoc tool. For those who are not familiar with Javadoc; this style of documentation is automatically generated based on comments found within java code. This is a wonderful feature of Java and really highlights the importance and benefits of comments within code. If you would like to learn how to comment your code so you can have automatic documentation created as well, check out the Javadoc standards. If you plan to work with Java in any professional capacity, this is a must!
You can set up NetBeans to automatically pull from the FCR Java API documentation by following the steps below:
- From the Tools menu, select Java Platforms
- Select the Javadoc tab
- Click the Add ZIP/Folder button
- Navigate to the %USERPROFILE%\sunspotfrcsdk\doc\javadoc folder mentioned before and click the Add ZIP/Folder button
- Restart NetBeans
Once configured correctly, NetBeans will utilize the FRC Java API Javadoc you pointed to for code completion, code verification, and Javadoc querys. For example, in a robot project, place the cursor on any method and press Shift + F1. This will automatically bring up documentation on the selected method. When typing, NetBeans will automatically use the Javadoc to suggest available methods.
Similarly for Eclipse:
- Right click on your Project folder in the Project Explorer window, click Build Path > Configure Build Path...
- Expand the classes.jar item
- Double click on Javadoc location
- Navigate to the %USERPROFILE%\sunspotfrcsdk\doc\javadoc folder mentioned above and click Validate (if you have the right directory it will tell you so).
- You may need to repeat steps 1-4 for the squawk-device.jar
- Restart Eclipse
Use the F2 hotkey to bring up a Javadoc summary popup for the selected code, or use the Shift + F2 key combination to bring up the full Javadoc in a new tab.
Note: The most up to date version of the FRC documentation should be available at: http://firstforge.wpi.edu/sf/projects/wpilib
There's also a good PDF that provides information about the API (pdf)