RFR [9] Warning notice for types in Incubator Modules

[Magnus Ihse Bursie]

On 2017-01-25 13:51, Chris Hegarty wrote:
>> On 24 Jan 2017, at 16:44, Erik Joelsson <erik.joelsson at oracle.com> 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