1. Home
  2. Portal
  3. Javadoc

Javadoc

D. U., modified 12 Years ago.
Javadoc
New Member Posts: 14 Join Date: 11/25/13 Recent Posts
What is the reason that most of the Liferay classes/methods have no Javadoc?
For instance, DLFolderServiceUtil.addFolder(...)
Not a single character of Javadoc can be found. I wanted to know what the boolean parameter mountPoint is for.
It is disappointing that the Liferay developers do not have a well programming manner. I know that a lot of programmer don't like to document their code but this is as important as the code itself.
When will the API be fully documented? Maybe the programmers should be teached better to do so. What about QA at Liferay? Is there any at all?

Another point: Abuse of programming constructs
For instance, DLAppLocalServiceUtil.getFolder(...)
Here is a Javadoc existent but exceptions are used to control the flow. Instead of returning a Folder object if any could be found or null if not, the method raises a PortalException if the folder can not be found. This makes the code around nasty and it is no good programming practice.
thumbnail
Cody Hoag, modified 12 Years ago.
RE: Javadoc
Junior Member Posts: 70 Join Date: 4/26/12 Recent Posts
Hi D.U.,

Liferay has put a heavy emphasis on producing more Javadoc for the coming year. Of course, as you stated already, there are many classes/methods with no Javadoc; so this will not be an overnight transformation. However, I've spoken with several Liferay developers that are willing and dedicated to providing Javadoc for their areas of expertise. You can view the public LRDOCS project to view ongoing Javadoc work, vote up Javadoc tickets, or create tickets for Javadoc classes/methods you'd like to see documented.
thumbnail
Adam Steiner, modified 12 Years ago.
RE: Javadoc
New Member Posts: 8 Join Date: 2/5/14 Recent Posts
Is it feasible to include community submissions in the API documentation process?

I know that there are people out there who want to contribute their findings about fringe methods/parameters and behaviors in a way that won't get lost in the noise of the community forums, blogs and wikis.

(I'm one of those people)
thumbnail
Cody Hoag, modified 12 Years ago.
RE: Javadoc
Junior Member Posts: 70 Join Date: 4/26/12 Recent Posts
Hi Adam,

We absolutely encourage community involvement with our API documentation (e.g, Javadoc). We have a public project in JIRA called LRDOCS where we track API documentation tickets. Let me give you a brief list of proper steps to take for submitting Javadoc.

  • Create an LRDOCS ticket for the Javadoc you plan to submit. Once you've submitted your Javadoc, assign that ticket to the person you submitted it to. This will enable Liferay to track your submission, preventing it from getting lost in the mix.
  • Liferay's Javadoc adheres to the Javadoc Guidelines. This should be referenced to make Javadoc submissions consistent to what we already have.
  • We submit Javadoc through Github pull requests. Please send your Javadoc submissions to @codyhoag in the liferay-portal repository.


Let me know if you have any other questions.