RFR: JDK-8175036 All API docs should be built for HTML 5

Martin Buchholz martinrb at google.com
Tue Apr 25 00:00:12 UTC 2017


[+javadoc-dev]

I'm no html expert, so don't trust anything I say, but:

jdk9 javadoc contains constructs that are clearly invalid html5, so
generating html5 output creates invalid web pages; they must be cleaned up
first.  Someone around here must have the expertise to know how best to
write modern html tables with borders.  The existing tables have mostly
been cargo-culted from file to file (including in java.util.concurrent).

Even if we can generate clean html5, I suspect it's too early to switch;
web standards change more slowly than anything else in the universe except
IPv6.  Whenever we're tempted to switch to a "modern" standard, we should
listen to How Many More Years? <http://www.youtube.com/embed/3NjXs_nXB5U> until
the feeling goes away.



On Sun, Apr 23, 2017 at 10:11 AM, Magnus Ihse Bursie <
magnus.ihse.bursie at oracle.com> wrote:

> Martin,
>
> Does this mean you oppose this change until all Javadoc compiles cleanly
> with doclint html5?
>
> /Magnus
>
> 22 apr. 2017 kl. 19:11 skrev Martin Buchholz <martinrb at google.com>:
>
> It seems our javadoc is using html constructs that are not valid html5.
> If so, we should convert all of those before we start generating html5
> output.  That should not be too much work for someone who actually
> understands css and html5.
>
> On Fri, Apr 21, 2017 at 2:30 AM, Magnus Ihse Bursie <
> magnus.ihse.bursie at oracle.com> wrote:
>
>> Jon,
>>
>> Can you please open a separate bug for this? Just adding --doclint-format
>> html5 generates a lot of failures, as Martin points out, so it's not
>> feasible to do as part of this fix.
>>
>> /Magnus
>>
>>
>> On 2017-04-21 03:08, Martin Buchholz wrote:
>>
>>> There would be a global cleanup involved for --doclint-format html5
>>> A CSS expert can probably suggest replacements.
>>>
>>>      [javac] ... src/main/java/util/Deque.java:30: error: attribute
>>> border
>>> for table only accepts "" or "1", use CSS instead: BORDER
>>>      [javac]  * <table BORDER CELLPADDING=3 CELLSPACING=1>
>>>
>>>
>>> On Thu, Apr 20, 2017 at 3:42 PM, Jonathan Gibbons <
>>> jonathan.gibbons at oracle.com> wrote:
>>>
>>> We probably want to set
>>>>
>>>> --doclint-format html5
>>>>
>>>> for javac as well, for the benefit of compilations that run doclint.
>>>>
>>>> -- Jon
>>>>
>>>>
>>>>
>>>> On 4/20/17 3:20 PM, Magnus Ihse Bursie wrote:
>>>>
>>>> We should switch all uses of the javadoc tool to generate documentation
>>>>> in HTML 5, using the -html5 option.
>>>>>
>>>>> Bug: https://bugs.openjdk.java.net/browse/JDK-8175036
>>>>> Patch inline:
>>>>> diff --git a/make/Javadoc.gmk b/make/Javadoc.gmk
>>>>> --- a/make/Javadoc.gmk
>>>>> +++ b/make/Javadoc.gmk
>>>>> @@ -84,7 +84,7 @@
>>>>>   # The initial set of options for javadoc
>>>>>   JAVADOC_OPTIONS := -XDignore.symbol.file=true -use -keywords
>>>>> -notimestamp \
>>>>>       -serialwarn -encoding ISO-8859-1 -breakiterator -splitIndex
>>>>> --system
>>>>> none \
>>>>> -    --expand-requires transitive
>>>>> +    -html5 --expand-requires transitive
>>>>>
>>>>>   # Should we add DRAFT stamps to the generated javadoc?
>>>>>   ifeq ($(VERSION_IS_GA), true)
>>>>>
>>>>> /Magnus
>>>>>
>>>>>
>>>>
>>
>



More information about the build-dev mailing list