No, for most buildings including PR verification, develop check-in, we don't have to run javadoc phase. The issue was exposed when I tried to deploy snapshot artifacts, using jdk1.8.x to compile and execute deploying commands which include the javadoc phase by default.
On Thu, Aug 25, 2016 at 12:53 PM, Edward Zhang <[email protected]> wrote: > 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 <[email protected]> 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 <[email protected]> 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 <[email protected]> > 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 > > >> > > > > >
