Run 'mvn javadoc:javadoc javadoc:test-javadoc', it now immediately failed :-(
So looks like mvn javadoc can find out useless param. Do we need do both checkstyle and javadoc while in building? [ERROR] Failed to execute goal org.apache.maven.plugins:maven-javadoc-plugin:2.9.1:javadoc (default-cli) on project alert-common: An error has occurred in JavaDocs report generation: [ERROR] Exit code: 1 - /Users/yonzhang/projects/incubator-eagle/eagle-core/eagle-alert-parent/eagle-alert/alert-common/src/main/java/org/apache/eagle/alert/config/ConfigBusProducer.java:32: warning: no description for @param [ERROR] * @param topic [ERROR] ^ [ERROR] /Users/yonzhang/projects/incubator-eagle/eagle-core/eagle-alert-parent/eagle-alert/alert-common/src/main/java/org/apache/eagle/alert/config/ConfigBusProducer.java:33: warning: no description for @param [ERROR] * @param config [ERROR] ^ On Wed, Aug 24, 2016 at 9:55 AM, Julian Hyde <jh...@apache.org> wrote: > 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 > >> > >
