Actually, when we build with jdk1.7, all go well with javadoc, the issue only cause by stricter rules of jdk1.8's javadoc which enables doclint. I find a way of loosen the restriction of jdk1.8 javadoc, and have configured it in the project's pom.xml so that we don't have to change build command respectively for jdk1.7 and jdk1.8. Ticket EAGLE-489 is trackable for this issue, I will open a PR soon.
On Thu, Aug 25, 2016 at 1:26 PM, Chen, Hao <[email protected]> wrote: > 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 > > > >> > > > > > > > > >
