On Fri, Sep 30, 2016 at 1:42 PM, Deron Eriksson <[email protected]> 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/
