I do not see how these automatically generated javadocs are useful. For instance:
/** * * @param pb * @param ec * @return * @throws DMLRuntimeException */ public static double getTimeEstimate(ProgramBlock pb, ExecutionContext ec, boolean recursive) throws DMLRuntimeException Here, someone has automatically generated a javadoc comment. The developer has failed to correct the missing 'recursive' parameter. If a developer has not created a blank javadoc comment in the first place, then the recursive parameter mistake never would have been made because there never would have been a blank javadoc comment to update in the first place. If automatically generated javadoc comments are decided to be part of our coding standard, then they should be applied to all methods, not just random methods. Deron On Fri, Sep 30, 2016 at 1:10 PM, Matthias Boehm <mbo...@us.ibm.com> wrote: > actually, I would prefer to leave the empty (automatically generated) > javadoc comments - at least in eclipse, this provides a better overview of > parameters and exceptions. > > Regards, > Matthias > > [image: Inactive hide details for Deron Eriksson ---09/30/2016 12:35:30 > PM---Hi Luciano, I am definitely in favor of fixing these javad]Deron > Eriksson ---09/30/2016 12:35:30 PM---Hi Luciano, I am definitely in favor > of fixing these javadocs. I created > > From: Deron Eriksson <deroneriks...@gmail.com> > To: dev@systemml.incubator.apache.org > Date: 09/30/2016 12:35 PM > Subject: Re: Enhancing SystemML JavaDocs > ------------------------------ > > > > Hi Luciano, > > I am definitely in favor of fixing these javadocs. I created > https://issues.apache.org/jira/browse/SYSTEMML-842 two months ago to > address this issue. > > However, there are so many problems with the javadocs that I think > addressing this should probably be broken down into separate java packages. > I would estimate that it's probably at least 20 hours of total work. > Therefore, it would be good if this could be addressed by multiple people. > > I would be in favor of: > (1) removing existing useless javadoc comments that are just automatically > generated by IDEs, since these serve no useful purpose. > (2) fix incorrect existing javadoc comments (for example, if the comments > are wrong about the actual method parameters). > > I like the idea of this being a blocker for 1.0 since this will force this > unpleasant but needed task to be accomplished. > > Deron > > > > > On Fri, Sep 30, 2016 at 11:54 AM, Luciano Resende <luckbr1...@gmail.com> > wrote: > > > Currently we have a bunch of wrong, incomplete or obsolete javadocs on > our > > APIs, and this continue o grow because we have the following > configuration > > in our build: > > > > <profile> > > <!-- Need to ignore doclint warnings for javadocs generated > on > > Java 8 until warnings are fixed --> > > <id>ignore-doclint-warnings-for-javadocs-on-java-8</id> > > <activation> > > <jdk>[1.8,)</jdk> > > </activation> > > <properties> > > <javadoc.opts>-Xdoclint:none</javadoc.opts> > > </properties> > > </profile> > > > > > > I know we are very close to 0.11 release to fix this, but I would like to > > make this issue as blocker for our next release (1.0 release), and thus > > would like to get everybody to give it a try by removing this > configuration > > and trying to build SystemML and fix a few of the Javadoc issues. > > > > If we can get a few PRs per week, we can fix this very quick for the next > > release. > > > > Thoughts ? > > > > > > -- > > Luciano Resende > > http://twitter.com/lresende1975 > > http://lresende.blogspot.com/ > > > > >
