Javadoc and Java 8

[Oliver Lietz <ap...@oliverlietz.de>]

hi all,

Javadoc became much stricter with doclint in Java 8 and releasing some (most?) 
of our modules with Java 8 will fail with Javadoc errors.

Should Javadoc errors block a release?

Should we enable Javadoc for regular builds?

We can disable doclint for builds with Java 8 or fix the errors (+1) of course 
to get around.

Regards,
O.

Re: Javadoc and Java 8

[Carsten Ziegeler <cz...@apache.org>]

Carsten Ziegeler wrote
> Oliver Lietz wrote
>> hi all,
>>
>> Javadoc became much stricter with doclint in Java 8 and releasing some (most?) 
>> of our modules with Java 8 will fail with Javadoc errors.
>>
>> Should Javadoc errors block a release?
>>
>> Should we enable Javadoc for regular builds?
>>
>> We can disable doclint for builds with Java 8 or fix the errors (+1) of course 
>> to get around.
>>
> 
> I think javadoc errors should block the release and we should fix them.
> A release is still possible if you simply use java 7, so a simple
> workaround exists.
> 
> I guess it would make sense to enable javadoc building on our CI server,
> however as we're not paying that much attention to what is happening
> there anyway, I'm not sure if it helps.
> 
> Fixing the javadoc for java 8 is not the nicest task in the world, but
> you can usually do this fairly quickly.
> 

And this is also a good opportunity to see whether the javadoc
generation for a module works as expected or not. As  I just found out
while fixing the javadocs for the eventing module: the package excludes
where not handled correctly at all.

Carsten
 
-- 
Carsten Ziegeler
Adobe Research Switzerland
cziegeler@apache.org

Re: Javadoc and Java 8

[Oliver Lietz <ap...@oliverlietz.de>]

On Thursday 07 July 2016 11:05:28 Bertrand Delacretaz wrote:
> On Thu, Jul 7, 2016 at 9:41 AM, Carsten Ziegeler <cz...@apache.org> 
wrote:
> > ...Fixing the javadoc for java 8 is not the nicest task in the world, but
> > you can usually do this fairly quickly....
> 
> I agree with that - the problem is that this pollutes diffs when
> comparing the code of a previous version of a module with a new
> release, which I often do.

Well, even more important to get Javadocs right from the beginning.

> But that's life I guess...
> 
> I'm ok for aiming to fix the javadocs, while being able to do releases
> with java 7 in the meantime.

There are some new rules in Java 8 which are arguable, but looking at e.g. 
RepoInitParser the comments are just plain wrong (outdated).

Regards,
O.

> -Bertrand

Re: Javadoc and Java 8

[Bertrand Delacretaz <bd...@apache.org>]

On Thu, Jul 7, 2016 at 9:41 AM, Carsten Ziegeler <cz...@apache.org> wrote:
> ...Fixing the javadoc for java 8 is not the nicest task in the world, but
> you can usually do this fairly quickly....

I agree with that - the problem is that this pollutes diffs when
comparing the code of a previous version of a module with a new
release, which I often do.

But that's life I guess...

I'm ok for aiming to fix the javadocs, while being able to do releases
with java 7 in the meantime.

-Bertrand

Re: Javadoc and Java 8

[Carsten Ziegeler <cz...@apache.org>]

Oliver Lietz wrote
> hi all,
> 
> Javadoc became much stricter with doclint in Java 8 and releasing some (most?) 
> of our modules with Java 8 will fail with Javadoc errors.
> 
> Should Javadoc errors block a release?
> 
> Should we enable Javadoc for regular builds?
> 
> We can disable doclint for builds with Java 8 or fix the errors (+1) of course 
> to get around.
> 

I think javadoc errors should block the release and we should fix them.
A release is still possible if you simply use java 7, so a simple
workaround exists.

I guess it would make sense to enable javadoc building on our CI server,
however as we're not paying that much attention to what is happening
there anyway, I'm not sure if it helps.

Fixing the javadoc for java 8 is not the nicest task in the world, but
you can usually do this fairly quickly.

Carsten
-- 
Carsten Ziegeler
Adobe Research Switzerland
cziegeler@apache.org