RFR [9] Warning notice for types in Incubator Modules

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

RFR [9] Warning notice for types in Incubator Modules

Chris Hegarty
As per the guidance in JEP 11 [1], the javadoc for types in
incubator modules should have a clear and explicit warning
notice. To that end, I’ve added a simple inline taglet that can
be used to effectively inject a standard notice, and applied it
to all public types in the HTTP module ( I’ll cleanup the line
width formatting before pushing ).

http://cr.openjdk.java.net/~chegar/incubator_taglet/

-Chris.

P.S. this work is, somewhat, in preparation for when we move
to a single documentation bundle [2].

[1] http://openjdk.java.net/jeps/11
[2] http://openjdk.java.net/jeps/299
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: RFR [9] Warning notice for types in Incubator Modules

Erik Joelsson
Hello,

Build changes look good except for one thing. In Javadoc.gmk, the
dependency on $(BUILD_TOOLS_JDK) needs to be set for $$($1_INDEX_FILE)
(on line 317), where the actual recipes are created. Setting it on the
phony docs-javadoc target will not help incremental builds.

/Erik


On 2017-01-24 15:08, Chris Hegarty wrote:

> As per the guidance in JEP 11 [1], the javadoc for types in
> incubator modules should have a clear and explicit warning
> notice. To that end, I’ve added a simple inline taglet that can
> be used to effectively inject a standard notice, and applied it
> to all public types in the HTTP module ( I’ll cleanup the line
> width formatting before pushing ).
>
> http://cr.openjdk.java.net/~chegar/incubator_taglet/
>
> -Chris.
>
> P.S. this work is, somewhat, in preparation for when we move
> to a single documentation bundle [2].
>
> [1] http://openjdk.java.net/jeps/11
> [2] http://openjdk.java.net/jeps/299

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

Re: RFR [9] Warning notice for types in Incubator Modules

Michael McMahon
In reply to this post by Chris Hegarty
Hi Chris

As regards the networking changes, they look fine to me.
As discussed off list, I think the link generated by the @Incubating
tag might possibly point to a new page in the docs bundle rather than
directly to the JEP 11 page. But, that can be the subject of another change.

Thanks,

Michael.

On 24/01/17 14:08, Chris Hegarty wrote:

> As per the guidance in JEP 11 [1], the javadoc for types in
> incubator modules should have a clear and explicit warning
> notice. To that end, I’ve added a simple inline taglet that can
> be used to effectively inject a standard notice, and applied it
> to all public types in the HTTP module ( I’ll cleanup the line
> width formatting before pushing ).
>
> http://cr.openjdk.java.net/~chegar/incubator_taglet/
>
> -Chris.
>
> P.S. this work is, somewhat, in preparation for when we move
> to a single documentation bundle [2].
>
> [1] http://openjdk.java.net/jeps/11
> [2] http://openjdk.java.net/jeps/299

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

Re: RFR [9] Warning notice for types in Incubator Modules

Chris Hegarty
In reply to this post by Erik Joelsson

> On 24 Jan 2017, at 16:44, Erik Joelsson <[hidden email]> wrote:
>
> Hello,
>
> Build changes look good except for one thing. In Javadoc.gmk, the dependency on $(BUILD_TOOLS_JDK) needs to be set for $$($1_INDEX_FILE) (on line 317), where the actual recipes are created. Setting it on the phony docs-javadoc target will not help incremental builds.

Updated in place
  http://cr.openjdk.java.net/~chegar/incubator_taglet/

-Chris.

> /Erik
>
>
> On 2017-01-24 15:08, Chris Hegarty wrote:
>> As per the guidance in JEP 11 [1], the javadoc for types in
>> incubator modules should have a clear and explicit warning
>> notice. To that end, I’ve added a simple inline taglet that can
>> be used to effectively inject a standard notice, and applied it
>> to all public types in the HTTP module ( I’ll cleanup the line
>> width formatting before pushing ).
>>
>> http://cr.openjdk.java.net/~chegar/incubator_taglet/
>>
>> -Chris.
>>
>> P.S. this work is, somewhat, in preparation for when we move
>> to a single documentation bundle [2].
>>
>> [1] http://openjdk.java.net/jeps/11
>> [2] http://openjdk.java.net/jeps/299
>

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

Re: RFR [9] Warning notice for types in Incubator Modules

Erik Joelsson
Thanks, looks good now.

/Erik


On 2017-01-25 13:51, Chris Hegarty wrote:

>> On 24 Jan 2017, at 16:44, Erik Joelsson <[hidden email]> wrote:
>>
>> Hello,
>>
>> Build changes look good except for one thing. In Javadoc.gmk, the dependency on $(BUILD_TOOLS_JDK) needs to be set for $$($1_INDEX_FILE) (on line 317), where the actual recipes are created. Setting it on the phony docs-javadoc target will not help incremental builds.
> Updated in place
>    http://cr.openjdk.java.net/~chegar/incubator_taglet/
>
> -Chris.
>
>> /Erik
>>
>>
>> On 2017-01-24 15:08, Chris Hegarty wrote:
>>> As per the guidance in JEP 11 [1], the javadoc for types in
>>> incubator modules should have a clear and explicit warning
>>> notice. To that end, I’ve added a simple inline taglet that can
>>> be used to effectively inject a standard notice, and applied it
>>> to all public types in the HTTP module ( I’ll cleanup the line
>>> width formatting before pushing ).
>>>
>>> http://cr.openjdk.java.net/~chegar/incubator_taglet/
>>>
>>> -Chris.
>>>
>>> P.S. this work is, somewhat, in preparation for when we move
>>> to a single documentation bundle [2].
>>>
>>> [1] http://openjdk.java.net/jeps/11
>>> [2] http://openjdk.java.net/jeps/299

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

Re: RFR [9] Warning notice for types in Incubator Modules

Magnus Ihse Bursie
In reply to this post by Chris Hegarty
On 2017-01-25 13:51, Chris Hegarty wrote:

      
On 24 Jan 2017, at 16:44, Erik Joelsson [hidden email] wrote:

Hello,

Build changes look good except for one thing. In Javadoc.gmk, the dependency on $(BUILD_TOOLS_JDK) needs to be set for $$($1_INDEX_FILE) (on line 317), where the actual recipes are created. Setting it on the phony docs-javadoc target will not help incremental builds.
Updated in place
  http://cr.openjdk.java.net/~chegar/incubator_taglet/

It's not ideal that a top-level target has dependencies from the JDK repo, but since we have no or few pre-existing top-level tools, I understand if you hesitate to add a new framework for such tools. If we ever do introduce more such tools, I think we should move this along.

I think the new -taglet options to the DEFAULT_JAVADOC_OPTIONS variable. As  the documentation says, the DEFAULT_JAVADOC_TAGS is there to specify the ordering of tags in the output. Unless the -taglet options implicitly generates one or more -tag options in it's place, that's the wrong place to put it. If it does, perhaps a comment indicating this hidden behavior would be in place.

In the line: "$$($1_INDEX_FILE): $(BUILD_TOOLS_JDK) $$($1_VARDEPS_FILE) $$($1_PACKAGE_DEPS) $$($1_DEPS)", please use a double $ ($$) for all variables. While technically not necessary in this particular case, it's misleading and we've had our share of bugs due to single $ in eval'd macros.

In the line: "docs-javadoc: $(BUILD_TOOLS_JDK) $(TARGETS)", please remove the reference to BUILD_TOOLS_JDK. It is not needed.

/Magnus



-Chris.

/Erik


On 2017-01-24 15:08, Chris Hegarty wrote:
As per the guidance in JEP 11 [1], the javadoc for types in
incubator modules should have a clear and explicit warning
notice. To that end, I’ve added a simple inline taglet that can
be used to effectively inject a standard notice, and applied it
to all public types in the HTTP module ( I’ll cleanup the line
width formatting before pushing ).

http://cr.openjdk.java.net/~chegar/incubator_taglet/

-Chris.

P.S. this work is, somewhat, in preparation for when we move
to a single documentation bundle [2].

[1] http://openjdk.java.net/jeps/11
[2] http://openjdk.java.net/jeps/299

      

    

Loading...