systemml-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Luciano Resende <luckbr1...@gmail.com>
Subject Re: Enhancing SystemML JavaDocs
Date Fri, 30 Sep 2016 22:18:26 GMT
On Fri, Sep 30, 2016 at 1:42 PM, Deron Eriksson <deroneriksson@gmail.com>
wrote:

> 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
>
>

Completely agree Deron, these are becoming stale and obsolete with the APIs
being enhanced and the javadocs being left behind. In the past I actually
tried to fix some, but as you mentioned there is a lot and we need a
community effort here.

Another approach is to make javadocs update MANDATORY for PR acceptance,
meaning that, if you touch a given file, you fix any javadoc related to
that file.

Thoughts ?


-- 
Luciano Resende
http://twitter.com/lresende1975
http://lresende.blogspot.com/

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