This website uses cookies to ensure you get the best experience. Learn More.
Javadoc Contest
Another Liferay contest is on the way! This one, however, is a bit different than others you may have participated in previously. To celebrate the upcoming release of Liferay 7, we are holding a community Javadoc contest. It's simple; you write Javadoc for parts of Liferay you have expert knowledge on, and you accumulate points based on the amount of documentation you provide.
In the early years of Liferay, documentation was a sore subject among Liferay users and community members. This has changed drastically over the years and has culminated in Liferay's Developer Network. Another area Liferay is looking to drastically improve is its API reference documentation (API docs). Because this is such a large task, we're calling on our community to assist. Liferay held an internal Javadoc contest, which garnered enthusiasm about writing API docs from within the company. The winner of our internal contest, Olaf Kock, gave some good advice for how the Javadoc transformation can be done quickly. His paraphrased advice: If many developers using Liferay provide Javadoc for the areas they have a deep understanding for, whether that be a couple methods or an entire package, Liferay will quickly see a turnaround in overall source code documentation. For more motivation, getting the recognition of Top Javadoc Contributor is a nice bragging right.
The top contributors will win an awesome Liferay Javadoc Master t-shirt (see graphic below).
So when you’re bragging about being a Javadoc expert to your friends and colleagues, you can have some proof to back it up.
March 8: Contest Opens
May 6: Last day to submit Javadoc
May 13: Winners announced
This gives you approximately eight weeks to submit as much Javadoc as possible for the contest.
Liferay provides comprehensive Javadoc Guidelines that explains the rules for writing Javadoc. In fact, these guidelines are so comprehensive that they are split up into two major sections: Javadoc Guidelines and Advanced Javadoc Guidelines. Start with the Javadoc Guidelines if you're a newbie and want to learn the basics. If you know the general rules and are looking for specific examples for a use case, the Advanced Javadoc Guidelines is where you want to visit.
Once you've committed your Javadoc using Git, you can send a pull request to liferay/liferay-portal with your changes and tag @codyhoag in the pull request comments. Be sure to only include Javadoc; no code changes please!
We're placing an emphasis on higher level areas. This means package description > class description > method description. The following point values apply:
Package: 3 points
Class: 2 points
Method 1 point
The points will be tallied for each contributor and standings will be posted frequently to the following Javadoc Contest Standings forum post. Make sure to subscribe to this forum post for updates.
Warning: Although this is a contest judged on the amount of content submitted, please strive to produce Javadoc that would be helpful for developers. Contest judges have the right to nullify contest points if it is obvious the submitter did not exert the appropriate effort necessary to write a useful description.
Submitted Javadoc will be reviewed by a lead developer for the area you documented to check for accuracy. The Javadoc will be reviewed again by the lead technical writer of the area to ensure the Javadoc Guidelines have been followed. We understand that not everyone is a native English speaker or has a fancy writing degree hanging in their office. We want Liferay knowledge, and we'll take care of the rest!
Again, please subscribe to the Javadoc Contest Standings forum post if you’re interested in following or participating in the contest. Good luck and happy Javadoc'ing!
