This bugs me too. FWIW, in Calcite we run ‘mvn javadoc:javadoc javadoc:test-javadoc’ as part of the automated build (as of JDK 1.8, javadoc is quite strict). Neither javadoc nor checkstyle will flag useless javadoc like ‘@param x’, so I wrote a checkstyle module[1] and call it from Calcite’s check style config[2].
Julian [1] https://github.com/julianhyde/toolbox <https://github.com/julianhyde/toolbox> [2] https://issues.apache.org/jira/browse/CALCITE-1034 <https://issues.apache.org/jira/browse/CALCITE-1034> > On Aug 24, 2016, at 12:13 AM, Hao Chen <h...@apache.org> wrote: > > Good reminding. @Contributors, not only about java docs, pls. make sure all > the code style matches the checkstyle, currently I just keep the checkstyle > as WARNING as we still have lots of style warning to clean, in future we > should throw ERROR if any check-style doesn't match. Pls. start to spend > sometime cleaning the checkstyle warning in your code right now. > > - Hao > > On Wed, Aug 24, 2016 at 3:04 PM, Michael Wu <mchl....@gmail.com> wrote: > >> Hi guys, >> >> Recently, when I tried to deploy eagle 0.5.0-incubating-snapshot artifacts >> based on develop branch, the entire build flow was broken by lots of faulty >> javadoc, which are classified in following aspects. I'll try to erase >> illegal/meaningless javadoc, and please PAY ATTENTION to your contribution >> and avoid checking-in such inappropriate javadoc: >> >> 1. Illegal character found, e.g. "<", or ">". Except for recognized html >> tags, such as "<pre></pre>", "<b></b>", etc., other angle brackets should >> be replaced with entities, say, "<" should be "<", and ">" should be >> ">". >> >> 2. Many "<p>" and "</p>" found in apache license comment, enclosing the >> license url. This kind of "p" tag is not allowed by javadoc, and actually, >> it's useless to be placed in the license comment either. Next time you >> create a new java file, please refer to another existing java file and >> copy+paste the correct license comment to the head of your new file, and >> make sure it does contain the "<p></p>" pair around the license url. >> >> 3. Many meaningless parameters and javadoc blocks found in files. This >> issue could be more descriptive with a sample, see below javadoc fragment >> that appears many times in eagle project on develop branch: >> /** >> * >> * @param arg1 >> * @param arg2 >> * @return >> */ >> This is a sample for rather meaningless javadoc. First, if there is no >> description, why shall we add this javadoc? Seconds, if we don't add >> description for arguments, who can know what to pass to the methods exactly >> by reading the javadoc? Third, if we don't add description for return >> value, how can customers understand the returning stuff by reading the >> javadoc? As a whole, such javadoc should be erased because we are not >> adding javadoc just for "adding", but for users or even code writers >> themselves to understand code more clearly. >> >> 4. Wrong upper case javadoc tag found. E.g. "@since" should be written in >> all lowercase, but found as "@Since", which make the javadoc generator >> complain with errors. >> >> So far, I've deployed eagle 0.5.0-incubating-snapshot to apache maven >> snapshot repository ( >> https://repository.apache.org/content/repositories/ >> snapshots/org/apache/eagle/). >> It currently doesn't include javadoc jars because there were too many >> javadoc error occurring while I was building the artifacts. When I erased >> incorrect ones in a sub model, that model ran pass and the next model in >> building chain raised up to complain. Therefore, it may cost me more time >> to erase all the faulty javadoc until all models are built successfully. >> >> Thank you for your understanding and cooperation. >> >> Michael >>
