Wow, I was not aware that those empty JavaDocs were put in -- and left in -- on purpose! To me they are the epitome of useless comments. At best they convey exactly the same information as the line of code immediately below them. Much of the time they end up conveying an incorrect, out-of-date version of the same. And all of the time they limit the amount of useful code that can be on screen at once. Are there many people on the project who actually like the current JavaDoc policy?
Fred From: Luciano Resende <luckbr1...@gmail.com> To: dev@systemml.incubator.apache.org Date: 09/30/2016 03:18 PM Subject: Re: Enhancing SystemML JavaDocs On Fri, Sep 30, 2016 at 1:42 PM, Deron Eriksson <deroneriks...@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/