I fear there is not much to discuss. The standard handling of javadoc has not changed. It's just that the plugin now aborts with an error or reports tons of warnings on really peanut situations like a missing @param.
There are 2 other points we need to take care: 1.) this must only be activated in java 8. If you set the -Xdocling=-missing on older javadoc versions, then they report a wrong parameter 2.) the parameters must get split due to a bug in our maven-javadoc-plugin atm. We cannot write -Xdoclint=all,-missing because the ',' leads to a parameter split and in the 'options' file it ends up as 2 parameters: ... -DXdoclint -missing ... which javadoc cannot parse. I played with it and found a workaround by using separate parameters: -Xdoclint=all -Xdoclint=-missing -Xdoclint=-html This version seems to work. What does it do? The javadoc warnings are basically fine imo (thus enabling 'all'). But logging a line or even breaking the build if a @param is missing is just ridiculous. I hate having all the empty (and thus useless) @param , @return, @throws lines if they contain no valuable info... The same thing happens with html all the time. Javadoc doesn't seem to natively understand xhtml. So writing a </p> causes an error. Which is really odd... As you already did say: we do not like to have all 250 projects depending on apache-parent to implement all this on their own ;) LieGrue, strub On Thursday, 1 May 2014, 22:33, Robert Scholte <rfscho...@apache.org> wrote: Hi Mark, > >I think we need to make a decision for the plugin first on how to handle >this. > >IMHO it's not the task of the maven-javadoc-plugin to maintain backwards >compatibility because Oracle has decided to change the behavior. >However, if we keep it like it is, we'll get a huge number of jira issues >blaming the maven-javadoc-plugin to be broken. > >Since we can't tell if the javadoc errors were based old or new code >changes, we might need to give a message/disclaimer describing that the >build could have failed due to the changes of the javadoc executable. >Add to that message the xdoclint options to get the original behavior. > >regarding the parent, we probably also want to add -reference ( as >suggested by one of the Oracle developers ) > >thanks, >Robert > >Op Thu, 01 May 2014 12:15:45 +0200 schreef Mark Struberg ><strub...@yahoo.de>: > > >> Hi! >> >> Building with Java8 breaks buiding JavaDocs many existing maven projects. >> And thus most times also breaks releasing them. >> >> The reason is that they enabled all warnings and errors now by default. >> This means that we get tons of oddly broken builds because it also >> breaks for missing @param, etc. >> >> I first had >> <additionalparam>-Xdoclint:none</additionalparam> >> But this is way too strict for apache-parent >> >> My next try was >> <additionalparam>-Xdoclint:all,-missing</additionalparam> >> But this triggers a bug in maven-javadoc-plugin because the comma gets >> used for splitting the parameters. And >> >>> -Xdoclint:all,-missing >> >> is really different to >>> -Xdoclint:all >>> -missing >> >> You can check it yourself in ./target/site/apidocs/options of your own >> projects. >> >> What seems to work is splitting them up into 2 parameters: >> >> <additionalparam>-Xdoclint:all -Xdoclint:-missing</additionalparam> >> >> >> Should we add this to apache-parent? >> Any other doclint tweaks you like to do for it? >> >> LieGrue, >> strub >> >> --------------------------------------------------------------------- >> To unsubscribe, e-mail: dev-unsubscr...@maven.apache.org >> For additional commands, e-mail: dev-h...@maven.apache.org > >--------------------------------------------------------------------- >To unsubscribe, e-mail: dev-unsubscr...@maven.apache.org >For additional commands, e-mail: dev-h...@maven.apache.org > > > > >
