systemml-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Deron Eriksson <deroneriks...@gmail.com>
Subject Re: Enhancing SystemML JavaDocs
Date Fri, 30 Sep 2016 20:42:41 GMT
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 <mboehm@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 <deroneriksson@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 <luckbr1975@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/
> >
>
>
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message