Looking ahead: how to enable doclint checking when building java.* and javax.*

[Jonathan Gibbons]

On 07/11/2013 09:09 AM, Erik Joelsson wrote:
>
>
> On 2013-07-11 00:32, Joe Darcy wrote:
>> On 07/10/2013 02:13 PM, Jonathan Gibbons wrote:
>>> On 07/10/2013 06:38 PM, Joe Darcy wrote:
>>>> Hello,
>>>>
>>>> Over on core-libs-dev, there has been a sequence of bug fixes to 
>>>> cleanup doclint warnings and errors in the  java.* and javax.* 
>>>> areas in JDK 8. A few weeks ago, there were over 2,000 doclint 
>>>> issues; currently there are about 850 remaining and we're making 
>>>> good progress slogging through the rest.
>>>>
>>>> Looking ahead a few weeks when we may have the happy situation of 
>>>> zero doclint issues in JDK 8, I wanted to ask on build-dev how 
>>>> doclint warnings and errors can be enabled via the makefiles when 
>>>> building the java.* and javax.* sources and how doclint issues can 
>>>> be made fatal. (Making doclint issues fatal will help discourage 
>>>> them from creeping back in ;-)
>>>>
>>>> Thanks,
>>>>
>>>> -Joe
>>>
>>> javac has a -Xdoclint option, similar to -Xlint that can enable 
>>> warnings at compile time.  The hope is that engineers will enable 
>>> that in their compilation environment and fix doc comment errors at 
>>> the same time as their compilation errors.
>>>
>>>
>>
>> Right; personally, I usually run doclint through javac vs. javadoc.
>>
>> Just to be clear, once we get doclint-clean, the functionality I'd 
>> like to see in the JDK build of the java[x].* classes is:
>>
>> * doclint gets run as part of compiling these types
>> * doclint errors are fatal
>> * doclint warnings are fatal too
> The new build compiles all (or at least most) java classes in one go. 
> This is good for speed, but loses on flexibility. I do not know of a 
> way to apply different sets of warnings to subsets of the sources 
> being compiled. The way this was handled in the old build, compiling 
> subsets of the source at a time, gave a bit more flexibility, but 
> instead lost on reliability as implicit compilation made it very hard 
> to reliably know which code was actually compiled with which set of 
> warnings.
>
> I believe Fredrik had future plans for sjavac to handle different sets 
> of compiler options for different subsets of source code, which could 
> be used to solve this problem. But that's not implemented (yet).
>
> /Erik

Just FYI, currently you can't make doclint warnings fatal without making 
all warnings fatal.   That's mostly OK since most javac warnings are 
opt-in by default, but there are some warnings that are always enabled.  
So we would need to make sure that those warnings are kept under control.

We might want to be selective about some of the doclint warnings to 
begin with, since some of the warnings require fixing by fixing the 
stylesheet (such as adding a new style).  But right now we are making 
good progress on fixing up comments and understanding the issues that 
still need to be addressed.

-- Jon

-- Jon