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

classic Classic list List threaded Threaded
8 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Magnus Ihse Bursie
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
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Jonathan Gibbons
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

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Martin Buchholz-3
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 <
[hidden email]> 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
>>
>
>
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Erik Joelsson
In reply to this post by Magnus Ihse Bursie
Looks good to me.

/Erik


On 2017-04-21 00:20, 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

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Magnus Ihse Bursie
In reply to this post by Martin Buchholz-3
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 <
> [hidden email]> 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
>>>
>>

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Martin Buchholz-3
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 <
[hidden email]> 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 <
>> [hidden email]> 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
>>>>
>>>>
>>>
>
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Magnus Ihse Bursie
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 <[hidden email]>:
>
> 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 <[hidden email]> 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 <
>>> [hidden email]> 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
>
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Jonathan Gibbons
In reply to this post by Magnus Ihse Bursie
I'll open a separate bug, but we'll have to decide how we sequence this.
It's already the case that we've mostly disabled doclint in javadoc, so
it is not significantly worse to disable it in javac for the time being
as well, until we get everything sorted out and consistent.

-- Jon


On 04/21/2017 02:30 AM, Magnus Ihse Bursie 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 <
>> [hidden email]> 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
>>>>
>>>
>

Loading...