Currently I ignored java doc check in checkstyle configuration: https://github.com/apache/incubator-eagle/blob/develop/eagle-dev/checkstyle.xml#L236
-----Original Message----- From: Michael Wu [mailto:[email protected]] Sent: 2016年8月25日 13:09 To: [email protected] Subject: Re: Please take notice to check-in only meaningful javadoc. 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 > > >> copy+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 > > >> > > > > >
