Quantcast

RFR: JDK-8172312 Update docs target and image for new combined docs

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

RFR: JDK-8172312 Update docs target and image for new combined docs

Magnus Ihse Bursie
As a part of JEP 299, we should build the Javadoc as a single combined
output, instead of a dozen or so individual javadoc bundles. This bug
fixes this. The selection on what to include is now based on modules
instead of packages.

The fix in MakeBase.gmk is to keep CacheFind quiet if the src dir(s)
does not exist, otherwise find can emit an error message. (This was
provoked by the new call to SetupZipArchive).

The module selection has been contributed by Mandy Chang.

I intend to push this to JDK9. Since this is a noreg-doc bug, no special
RDP2 process is required.

Bug: https://bugs.openjdk.java.net/browse/JDK-8172312
WebRev:
http://cr.openjdk.java.net/~ihse/JDK-8172312-combined-javadocs/webrev.01

/Magnus

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

Re: RFR: JDK-8172312 Update docs target and image for new combined docs

Erik Joelsson
Hello,

Javadoc.gmk:159 looks like too much indentation

The variable JAVADOC_SOURCE_DIRS is starting to seem a bit redundant. It
does contain two directories that would not be included if you replaced
$(call PathList, $(JAVADOC_SOURCE_DIRS)) with $(call GetModuleSrcPath),
but that could be rectified by adding $(SUPPORT_OUTPUTDIR)/rmic to
GENERATED_SRC_DIRS and share/doc/stub to SRC_SUBDIRS in Javadoc.gmk.
Doing so would make the dependency calculation and the actual source dir
input be based on the same definitions.

/Erik

On 2017-03-30 15:05, Magnus Ihse Bursie wrote:

> As a part of JEP 299, we should build the Javadoc as a single combined
> output, instead of a dozen or so individual javadoc bundles. This bug
> fixes this. The selection on what to include is now based on modules
> instead of packages.
>
> The fix in MakeBase.gmk is to keep CacheFind quiet if the src dir(s)
> does not exist, otherwise find can emit an error message. (This was
> provoked by the new call to SetupZipArchive).
>
> The module selection has been contributed by Mandy Chang.
>
> I intend to push this to JDK9. Since this is a noreg-doc bug, no
> special RDP2 process is required.
>
> Bug: https://bugs.openjdk.java.net/browse/JDK-8172312
> WebRev:
> http://cr.openjdk.java.net/~ihse/JDK-8172312-combined-javadocs/webrev.01
>
> /Magnus
>

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

Re: RFR: JDK-8172312 Update docs target and image for new combined docs

Mandy Chung
In reply to this post by Magnus Ihse Bursie

> On Mar 30, 2017, at 6:05 AM, Magnus Ihse Bursie <[hidden email]> wrote:
>
> As a part of JEP 299, we should build the Javadoc as a single combined output, instead of a dozen or so individual javadoc bundles. This bug fixes this. The selection on what to include is now based on modules instead of packages.
>
> The fix in MakeBase.gmk is to keep CacheFind quiet if the src dir(s) does not exist, otherwise find can emit an error message. (This was provoked by the new call to SetupZipArchive).
>
> The module selection has been contributed by Mandy Chang.
>
> I intend to push this to JDK9. Since this is a noreg-doc bug, no special RDP2 process is required.
>
> Bug: https://bugs.openjdk.java.net/browse/JDK-8172312 <https://bugs.openjdk.java.net/browse/JDK-8172312>
> WebRev: http://cr.openjdk.java.net/~ihse/JDK-8172312-combined-javadocs/webrev.01 <http://cr.openjdk.java.net/~ihse/JDK-8172312-combined-javadocs/webrev.01>


make/common/Modules.gmk

I should have cleaned this up in the sandbox and I will leave it for you if you don’t mind.
 141 #
 142 # Workaround --expand-requires transitive that does not include java.base
 143 #
 144 DOCS_MODULES += \
 145     java.base \
https://bugs.openjdk.java.net/browse/JDK-8176481 has been fixed.  This can be removed now.  It’d be good to add a comment something like this.

# DOCS_MODULES defines the root modules for javadoc generation.
# All of their `require transitive` modules directly and indirectly will be included.

I will file an issue to follow up the platform-specific modules.   Can you remove
 125   DOCS_MODULES += jdk.crypto.mscapi
 130   DOCS_MODULES += jdk.crypto.ucrypto
make/Javadoc.gmk
 224 REFERENCE_TARGET_DIR := $(SUPPORT_OUTPUTDIR)/javase-api
I suggest to name the javadoc output directory as “javase-docs/api” in the same layout as described in JEP 299.  It may copy the specs under javase-docs/specs directory in the future.
 239                 --module $(call CommaList, java.base java.se.ee))
java.base can be removed since JDK-8176481 has been resolved.
Mandy

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

Re: RFR: JDK-8172312 Update docs target and image for new combined docs

Magnus Ihse Bursie
In reply to this post by Erik Joelsson


On 2017-03-30 15:42, Erik Joelsson wrote:

> Hello,
>
> Javadoc.gmk:159 looks like too much indentation
>
> The variable JAVADOC_SOURCE_DIRS is starting to seem a bit redundant.
> It does contain two directories that would not be included if you
> replaced $(call PathList, $(JAVADOC_SOURCE_DIRS)) with $(call
> GetModuleSrcPath), but that could be rectified by adding
> $(SUPPORT_OUTPUTDIR)/rmic to GENERATED_SRC_DIRS and share/doc/stub to
> SRC_SUBDIRS in Javadoc.gmk. Doing so would make the dependency
> calculation and the actual source dir input be based on the same
> definitions.

This is a really nice idea! Unfortunately, it was not so easy. :-(

Adding rmic to GENERATED_SRC_DIRS causes java.base compilation to fail with:
Compiling 2898 files for java.base
warning: [path] bad path element
"/localhome/hg/jdk9-sandbox/build/linux-x64/support/rmic": no such directory
error: warnings found and -Werror specified
1 error

I could of course add an mkdir somewhere before java.base-java is
executed, but it doesn't really feel good. I think it's better to
explicitly add the rmic gensrc dir to the javadoc generation.

The same goes for the share/doc/stub. Adding it caused a whole bunch of
errors when compiling java.management.rmi:
/localhome/hg/jdk9-sandbox/jdk/src/java.rmi/share/doc/stub/java/rmi/activation/ActivationGroup_Stub.java:72:
warning: [rawtypes] found raw type: MarshalledObject
     public java.rmi.MarshalledObject newInstance(
                    ^
   missing type arguments for generic class MarshalledObject<T>
   where T is a type-variable:
...

I assume that the sole reason for putting ActivationGroup_Stub.java into
the "share/doc/stub" directory was to prohibit it from being part of
normal compilation.

So, once more, I'll rather add that directory to just the javadoc
generation.

Nevertheless, using $(call GetModuleSrcPath) instead is very nice, even
if I have to add a couple of paths.

New webrev coming up soon...

/Magnus

>
> /Erik
>
> On 2017-03-30 15:05, Magnus Ihse Bursie wrote:
>> As a part of JEP 299, we should build the Javadoc as a single
>> combined output, instead of a dozen or so individual javadoc bundles.
>> This bug fixes this. The selection on what to include is now based on
>> modules instead of packages.
>>
>> The fix in MakeBase.gmk is to keep CacheFind quiet if the src dir(s)
>> does not exist, otherwise find can emit an error message. (This was
>> provoked by the new call to SetupZipArchive).
>>
>> The module selection has been contributed by Mandy Chang.
>>
>> I intend to push this to JDK9. Since this is a noreg-doc bug, no
>> special RDP2 process is required.
>>
>> Bug: https://bugs.openjdk.java.net/browse/JDK-8172312
>> WebRev:
>> http://cr.openjdk.java.net/~ihse/JDK-8172312-combined-javadocs/webrev.01
>>
>> /Magnus
>>
>

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

Re: RFR: JDK-8172312 Update docs target and image for new combined docs

Magnus Ihse Bursie

On 2017-03-30 21:19, Magnus Ihse Bursie wrote:
>
> New webrev coming up soon...

Here it is:

http://cr.openjdk.java.net/~ihse/JDK-8172312-combined-javadocs/webrev.02

Changes since last webrev:

  * Removed java.base from DOCS_MODULES and updated comment.
  * Removed jdk.crypto.mscapi and jdk.crypto.ucrypto from DOCS_MODULES.
  * Replaced JAVADOC_SOURCE_DIRS with
     JAVADOC_SOURCE_PATH := $(call PathList, $(call GetModuleSrcPath) \
         $(SUPPORT_OUTPUTDIR)/rmic/* $(JDK_TOPDIR)/src/*/share/doc/stub)
    and added it to JAVADOC_VARDEPS
  * Fixed JAVADOC_TOP indentation
  * Removed java.base from list of modules for reference javase javadoc
  * Updated REFERENCE_TARGET_DIR to $(IMAGES_OUTPUTDIR)/javase-docs/api

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

Re: RFR: JDK-8172312 Update docs target and image for new combined docs

Mandy Chung

> On Mar 30, 2017, at 1:17 PM, Magnus Ihse Bursie <[hidden email]> wrote:
>
>
> On 2017-03-30 21:19, Magnus Ihse Bursie wrote:
>>
>> New webrev coming up soon...
>
> Here it is:
>
> http://cr.openjdk.java.net/~ihse/JDK-8172312-combined-javadocs/webrev.02

Looks good to me.

FYI. I created https://bugs.openjdk.java.net/browse/JDK-8177849 for the platform-specific modules issue.

Mandy

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

Re: RFR: JDK-8172312 Update docs target and image for new combined docs

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

My suggestion was to to add the rmic dirs to those variables in
Javadoc.gmk, but your solution is even better. I didn't realize that you
could just add to a "pathlist" with another call to PathList, so I
thought we had to get at the variables that GetModuleSrcPath uses as
input. Anyway, very nice to not have to duplicate the list of source
dirs anymore.

/Erik


On 2017-03-30 22:17, Magnus Ihse Bursie wrote:

>
> On 2017-03-30 21:19, Magnus Ihse Bursie wrote:
>>
>> New webrev coming up soon...
>
> Here it is:
>
> http://cr.openjdk.java.net/~ihse/JDK-8172312-combined-javadocs/webrev.02
>
> Changes since last webrev:
>
>  * Removed java.base from DOCS_MODULES and updated comment.
>  * Removed jdk.crypto.mscapi and jdk.crypto.ucrypto from DOCS_MODULES.
>  * Replaced JAVADOC_SOURCE_DIRS with
>     JAVADOC_SOURCE_PATH := $(call PathList, $(call GetModuleSrcPath) \
>         $(SUPPORT_OUTPUTDIR)/rmic/* $(JDK_TOPDIR)/src/*/share/doc/stub)
>    and added it to JAVADOC_VARDEPS
>  * Fixed JAVADOC_TOP indentation
>  * Removed java.base from list of modules for reference javase javadoc
>  * Updated REFERENCE_TARGET_DIR to $(IMAGES_OUTPUTDIR)/javase-docs/api
>
> /Magnus

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

Re: RFR: JDK-8172312 Update docs target and image for new combined docs

Magnus Ihse Bursie


On 2017-03-31 10:02, Erik Joelsson wrote:
> Looks good to me.
>
> My suggestion was to to add the rmic dirs to those variables in
> Javadoc.gmk, but your solution is even better. I didn't realize that
> you could just add to a "pathlist" with another call to PathList, so I
> thought we had to get at the variables that GetModuleSrcPath uses as
> input.

That's even documented! :-) "Safe for multiple nested calls."

> Anyway, very nice to not have to duplicate the list of source dirs
> anymore.

Yep, indeed.

/Magnus

>
> /Erik
>
>
> On 2017-03-30 22:17, Magnus Ihse Bursie wrote:
>>
>> On 2017-03-30 21:19, Magnus Ihse Bursie wrote:
>>>
>>> New webrev coming up soon...
>>
>> Here it is:
>>
>> http://cr.openjdk.java.net/~ihse/JDK-8172312-combined-javadocs/webrev.02
>>
>> Changes since last webrev:
>>
>>  * Removed java.base from DOCS_MODULES and updated comment.
>>  * Removed jdk.crypto.mscapi and jdk.crypto.ucrypto from DOCS_MODULES.
>>  * Replaced JAVADOC_SOURCE_DIRS with
>>     JAVADOC_SOURCE_PATH := $(call PathList, $(call GetModuleSrcPath) \
>>         $(SUPPORT_OUTPUTDIR)/rmic/* $(JDK_TOPDIR)/src/*/share/doc/stub)
>>    and added it to JAVADOC_VARDEPS
>>  * Fixed JAVADOC_TOP indentation
>>  * Removed java.base from list of modules for reference javase javadoc
>>  * Updated REFERENCE_TARGET_DIR to $(IMAGES_OUTPUTDIR)/javase-docs/api
>>
>> /Magnus
>

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

Re: RFR: JDK-8172312 Update docs target and image for new combined docs

mark.reinhold
In reply to this post by Magnus Ihse Bursie
2017/3/30 6:05:43 -0700, [hidden email]:
> As a part of JEP 299, we should build the Javadoc as a single combined
> output, instead of a dozen or so individual javadoc bundles. This bug
> fixes this. The selection on what to include is now based on modules
> instead of packages.

I'm worried that perhaps we've unified a bit too much here.

This patch does build all the Javadoc together, as advertised, but that
places the `jdk.*` modules together with the `java.*` modules under the
heading "Java Platform, Standard Edition 9 API Specification", and of
course the `jdk.*` modules aren't part of that spec.

JDK 9 is the "Reference Implementation" (in JCP terms) of Java SE 9, so
it's important to keep a clear distinction between the SE-standard parts
of the spec and those that are JDK-specific.

Would it make sense instead to have `docs/api` be just for the SE (i.e.,
`java.*`) modules, and then place the Javadoc for the `jdk.*` modules
under `docs/api/jdk`?  There could be a helpful link from the SE API
title page to the JDK API title page, but it should make it clear that
the JDK APIs aren't part of the SE spec.

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

Re: RFR: JDK-8172312 Update docs target and image for new combined docs

Magnus Ihse Bursie
Mark,

I think the distinction you ask for is already there. The two separate
make targets "docs-javadoc" and "docs-reference" builds two distinct
images "docs" and "javase-docs", respectively. The first of these builds
the complete Java SE + JDK documentation, the second build just the Java
SE documentation.

I do not think it's a good idea to go further and actually *remove* the
Java SE part from the complete "docs" image. Upholding such a formal
difference between different parts of the JDK is likely to be just
confusing to common Java developers. I believe that enforcing such a cut
would eliminate much of the work that has been put into giving the the
Java developer community a unified access to all releveant documentation.

With that said, we should change the heading so that only the
javase-docs image claims to be the SE specification. (Note that this
incorrect claim is not a regression, since this is what the core-docs
api has been saying since long time ago, even while containing
Oracle-specific classes...)

/Magnus

On 2017-04-01 20:25, [hidden email] wrote:

> 2017/3/30 6:05:43 -0700, [hidden email]:
>> As a part of JEP 299, we should build the Javadoc as a single combined
>> output, instead of a dozen or so individual javadoc bundles. This bug
>> fixes this. The selection on what to include is now based on modules
>> instead of packages.
> I'm worried that perhaps we've unified a bit too much here.
>
> This patch does build all the Javadoc together, as advertised, but that
> places the `jdk.*` modules together with the `java.*` modules under the
> heading "Java Platform, Standard Edition 9 API Specification", and of
> course the `jdk.*` modules aren't part of that spec.
>
> JDK 9 is the "Reference Implementation" (in JCP terms) of Java SE 9, so
> it's important to keep a clear distinction between the SE-standard parts
> of the spec and those that are JDK-specific.
>
> Would it make sense instead to have `docs/api` be just for the SE (i.e.,
> `java.*`) modules, and then place the Javadoc for the `jdk.*` modules
> under `docs/api/jdk`?  There could be a helpful link from the SE API
> title page to the JDK API title page, but it should make it clear that
> the JDK APIs aren't part of the SE spec.
>
> - Mark

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

Re: RFR: JDK-8172312 Update docs target and image for new combined docs

Jonathan Gibbons
Mark,

I agree there will need to be some cosmetic cleanup with respect to
headings. Given the optionality of whether or not the build is set to
import JavaFX, the headings and content of the new overview page will
need to be somewhat synthesized.

Separately, it has always been a requirement to support the generation
of "Java SE"-only docs, which can be produced independently of the
consolidated docs.

The advantage of being able to generate a single big bundle is that the
new "javadoc Search" feature will work as expected.  If we partition the
docs, then the scope of any search will be restricted to the subset of
docs currently being viewed.

-- Jon

On 04/03/2017 03:24 AM, Magnus Ihse Bursie wrote:

> Mark,
>
> I think the distinction you ask for is already there. The two separate
> make targets "docs-javadoc" and "docs-reference" builds two distinct
> images "docs" and "javase-docs", respectively. The first of these
> builds the complete Java SE + JDK documentation, the second build just
> the Java SE documentation.
>
> I do not think it's a good idea to go further and actually *remove*
> the Java SE part from the complete "docs" image. Upholding such a
> formal difference between different parts of the JDK is likely to be
> just confusing to common Java developers. I believe that enforcing
> such a cut would eliminate much of the work that has been put into
> giving the the Java developer community a unified access to all
> releveant documentation.
>
> With that said, we should change the heading so that only the
> javase-docs image claims to be the SE specification. (Note that this
> incorrect claim is not a regression, since this is what the core-docs
> api has been saying since long time ago, even while containing
> Oracle-specific classes...)
>
> /Magnus
>
> On 2017-04-01 20:25, [hidden email] wrote:
>> 2017/3/30 6:05:43 -0700, [hidden email]:
>>> As a part of JEP 299, we should build the Javadoc as a single combined
>>> output, instead of a dozen or so individual javadoc bundles. This bug
>>> fixes this. The selection on what to include is now based on modules
>>> instead of packages.
>> I'm worried that perhaps we've unified a bit too much here.
>>
>> This patch does build all the Javadoc together, as advertised, but that
>> places the `jdk.*` modules together with the `java.*` modules under the
>> heading "Java Platform, Standard Edition 9 API Specification", and of
>> course the `jdk.*` modules aren't part of that spec.
>>
>> JDK 9 is the "Reference Implementation" (in JCP terms) of Java SE 9, so
>> it's important to keep a clear distinction between the SE-standard parts
>> of the spec and those that are JDK-specific.
>>
>> Would it make sense instead to have `docs/api` be just for the SE (i.e.,
>> `java.*`) modules, and then place the Javadoc for the `jdk.*` modules
>> under `docs/api/jdk`?  There could be a helpful link from the SE API
>> title page to the JDK API title page, but it should make it clear that
>> the JDK APIs aren't part of the SE spec.
>>
>> - Mark
>

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

Re: RFR: JDK-8172312 Update docs target and image for new combined docs

mark.reinhold
In reply to this post by Magnus Ihse Bursie
2017/4/3 3:24:52 -0700, [hidden email]:
> I think the distinction you ask for is already there. The two separate
> make targets "docs-javadoc" and "docs-reference" builds two distinct
> images "docs" and "javase-docs", respectively. The first of these builds
> the complete Java SE + JDK documentation, the second build just the Java
> SE documentation.

I'm glad that there's an SE-only target, but that's not what I asked
for.

> I do not think it's a good idea to go further and actually *remove* the
> Java SE part from the complete "docs" image.

That's not what I asked for, either.  I suggested making a stronger
distinction between the specifications of the SE APIs and those of the
rest of the JDK, by putting the latter in a subdirectory of the same
image.  Sorry if that wasn't clear.

>                                              Upholding such a formal
> difference between different parts of the JDK is likely to be just
> confusing to common Java developers. I believe that enforcing such a cut
> would eliminate much of the work that has been put into giving the the
> Java developer community a unified access to all releveant documentation.

I see your point, but failing to make a strong distinction could also
confuse developers, since it may lead some to use JDK-specific APIs when
they really want to write code that's portable to any SE implementation.

Still, there may be better ways to make that distinction, as Jon suggests
nearby.

> With that said, we should change the heading so that only the
> javase-docs image claims to be the SE specification.

Yes, we must do that, at a bare minimum.

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

Re: RFR: JDK-8172312 Update docs target and image for new combined docs

mark.reinhold
In reply to this post by Jonathan Gibbons
2017/4/3 11:01:13 -0700, [hidden email]:
> I agree there will need to be some cosmetic cleanup with respect to
> headings. Given the optionality of whether or not the build is set to
> import JavaFX, the headings and content of the new overview page will
> need to be somewhat synthesized.

Is it possible to have (up to) three sections of modules on the front
page, where the first is headed by an orange "Java SE Modules" box, the
second is "JavaFX Modules", and the third is "JDK Modules"?

That, plus an updated title and some prose to explain that the first
section is standard and the rest are not, would probably do the trick.

> The advantage of being able to generate a single big bundle is that the
> new "javadoc Search" feature will work as expected.  If we partition the
> docs, then the scope of any search will be restricted to the subset of
> docs currently being viewed.

I agree that a unified search experience is very useful.

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

Re: RFR: JDK-8172312 Update docs target and image for new combined docs

Jonathan Gibbons


On 04/03/2017 04:42 PM, [hidden email] wrote:

> 2017/4/3 11:01:13 -0700, [hidden email]:
>> I agree there will need to be some cosmetic cleanup with respect to
>> headings. Given the optionality of whether or not the build is set to
>> import JavaFX, the headings and content of the new overview page will
>> need to be somewhat synthesized.
> Is it possible to have (up to) three sections of modules on the front
> page, where the first is headed by an orange "Java SE Modules" box, the
> second is "JavaFX Modules", and the third is "JDK Modules"?
>
> That, plus an updated title and some prose to explain that the first
> section is standard and the rest are not, would probably do the trick.

I'm not sure that we can partition the modules table in the remaining
time for 9,
although I do like the suggestion.

My thought had been to focus on the prose, so that the introductory text
on the
page has 3 paragraphs with appropriate subheadings, for the 3 groups that
you mention.  I was hoping that the makefiles would then be able to
determine
which of those 3 sections would be appropriate for the docs bundle being
generated.

Going forward, I was thinking to repurpose the under-used -group option
to give something like the visual grouping you suggest.

See:
http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#group

Using the existing technology, it might be reasonably easy to change the
existing table, so that the Modules tab can replaced by a series of tabs
labelled  "All Modules", "Java SE Modules", "JavaFX Modules" and "JDK
Modules".

I can raise this with the rest of jaavdoc team to see how difficult that
would be
in the remaining time.


>
>> The advantage of being able to generate a single big bundle is that the
>> new "javadoc Search" feature will work as expected.  If we partition the
>> docs, then the scope of any search will be restricted to the subset of
>> docs currently being viewed.
> I agree that a unified search experience is very useful.
>
> - Mark

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

Re: RFR: JDK-8172312 Update docs target and image for new combined docs

Magnus Ihse Bursie
In reply to this post by mark.reinhold
Here is an updated webrev:
http://cr.openjdk.java.net/~ihse/JDK-8172312-combined-javadocs/webrev.03

The only change compared to the previous webrev is that I have updated
the title for the JDK javadocs so it does not claim to be Java SE.

I have filed the following follow-up bugs to address Mark's concerns,
and concerns expressed elsewhere:

* JDK-8178043 Group Java SE, JDK and JavaFX modules in unified javadoc [1]
* JDK-8178037 Move information from jdi-overview.html into jdk.jdi
module-info.java [2]
* JDK-8178038 Copy jdwp-protocol.html to proper location [3]
* JDK-8178039 Copy jvmti.html to proper location [4]

I hope JDK-8178043 captures the intent of the solution I understand that
Mark and Jon seemed to agree upon.

I also refer to the previously existing:

* JDK-8175824 Provide more flexible means for setting the overview text
in the generated docs [5]

which I have amended with the task of also making sure that the values
of the title text snippets gets proper values.

Since a lot of the continued work on Javadoc changes in JDK 9 is
dependent on this change, I hope it is now clear for pushing.

/Magnus

[1] https://bugs.openjdk.java.net/browse/JDK-8178043
[2] https://bugs.openjdk.java.net/browse/JDK-8178037
[3] https://bugs.openjdk.java.net/browse/JDK-8178038
[4] https://bugs.openjdk.java.net/browse/JDK-8178039
[5] https://bugs.openjdk.java.net/browse/JDK-8175824


On 2017-04-04 01:38, [hidden email] wrote:

> 2017/4/3 3:24:52 -0700, [hidden email]:
>> I think the distinction you ask for is already there. The two separate
>> make targets "docs-javadoc" and "docs-reference" builds two distinct
>> images "docs" and "javase-docs", respectively. The first of these builds
>> the complete Java SE + JDK documentation, the second build just the Java
>> SE documentation.
> I'm glad that there's an SE-only target, but that's not what I asked
> for.
>
>> I do not think it's a good idea to go further and actually *remove* the
>> Java SE part from the complete "docs" image.
> That's not what I asked for, either.  I suggested making a stronger
> distinction between the specifications of the SE APIs and those of the
> rest of the JDK, by putting the latter in a subdirectory of the same
> image.  Sorry if that wasn't clear.
>
>>                                               Upholding such a formal
>> difference between different parts of the JDK is likely to be just
>> confusing to common Java developers. I believe that enforcing such a cut
>> would eliminate much of the work that has been put into giving the the
>> Java developer community a unified access to all releveant documentation.
> I see your point, but failing to make a strong distinction could also
> confuse developers, since it may lead some to use JDK-specific APIs when
> they really want to write code that's portable to any SE implementation.
>
> Still, there may be better ways to make that distinction, as Jon suggests
> nearby.
>
>> With that said, we should change the heading so that only the
>> javase-docs image claims to be the SE specification.
> Yes, we must do that, at a bare minimum.
>
> - Mark

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

Re: RFR: JDK-8172312 Update docs target and image for new combined docs

Erik Joelsson
Looks good to me.

/Erik


On 2017-04-04 13:47, Magnus Ihse Bursie wrote:

> Here is an updated webrev:
> http://cr.openjdk.java.net/~ihse/JDK-8172312-combined-javadocs/webrev.03
>
> The only change compared to the previous webrev is that I have updated
> the title for the JDK javadocs so it does not claim to be Java SE.
>
> I have filed the following follow-up bugs to address Mark's concerns,
> and concerns expressed elsewhere:
>
> * JDK-8178043 Group Java SE, JDK and JavaFX modules in unified javadoc
> [1]
> * JDK-8178037 Move information from jdi-overview.html into jdk.jdi
> module-info.java [2]
> * JDK-8178038 Copy jdwp-protocol.html to proper location [3]
> * JDK-8178039 Copy jvmti.html to proper location [4]
>
> I hope JDK-8178043 captures the intent of the solution I understand
> that Mark and Jon seemed to agree upon.
>
> I also refer to the previously existing:
>
> * JDK-8175824 Provide more flexible means for setting the overview
> text in the generated docs [5]
>
> which I have amended with the task of also making sure that the values
> of the title text snippets gets proper values.
>
> Since a lot of the continued work on Javadoc changes in JDK 9 is
> dependent on this change, I hope it is now clear for pushing.
>
> /Magnus
>
> [1] https://bugs.openjdk.java.net/browse/JDK-8178043
> [2] https://bugs.openjdk.java.net/browse/JDK-8178037
> [3] https://bugs.openjdk.java.net/browse/JDK-8178038
> [4] https://bugs.openjdk.java.net/browse/JDK-8178039
> [5] https://bugs.openjdk.java.net/browse/JDK-8175824
>
>
> On 2017-04-04 01:38, [hidden email] wrote:
>> 2017/4/3 3:24:52 -0700, [hidden email]:
>>> I think the distinction you ask for is already there. The two separate
>>> make targets "docs-javadoc" and "docs-reference" builds two distinct
>>> images "docs" and "javase-docs", respectively. The first of these
>>> builds
>>> the complete Java SE + JDK documentation, the second build just the
>>> Java
>>> SE documentation.
>> I'm glad that there's an SE-only target, but that's not what I asked
>> for.
>>
>>> I do not think it's a good idea to go further and actually *remove* the
>>> Java SE part from the complete "docs" image.
>> That's not what I asked for, either.  I suggested making a stronger
>> distinction between the specifications of the SE APIs and those of the
>> rest of the JDK, by putting the latter in a subdirectory of the same
>> image.  Sorry if that wasn't clear.
>>
>>> Upholding such a formal
>>> difference between different parts of the JDK is likely to be just
>>> confusing to common Java developers. I believe that enforcing such a
>>> cut
>>> would eliminate much of the work that has been put into giving the the
>>> Java developer community a unified access to all releveant
>>> documentation.
>> I see your point, but failing to make a strong distinction could also
>> confuse developers, since it may lead some to use JDK-specific APIs when
>> they really want to write code that's portable to any SE implementation.
>>
>> Still, there may be better ways to make that distinction, as Jon
>> suggests
>> nearby.
>>
>>> With that said, we should change the heading so that only the
>>> javase-docs image claims to be the SE specification.
>> Yes, we must do that, at a bare minimum.
>>
>> - Mark
>

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

Re: RFR: JDK-8172312 Update docs target and image for new combined docs

mark.reinhold
In reply to this post by Magnus Ihse Bursie
2017/4/4 4:47:58 -0700, [hidden email]:

> Here is an updated webrev:
> http://cr.openjdk.java.net/~ihse/JDK-8172312-combined-javadocs/webrev.03
>
> The only change compared to the previous webrev is that I have updated
> the title for the JDK javadocs so it does not claim to be Java SE.
>
> I have filed the following follow-up bugs to address Mark's concerns,
> and concerns expressed elsewhere:
>
> * JDK-8178043 Group Java SE, JDK and JavaFX modules in unified javadoc [1]
> * JDK-8178037 Move information from jdi-overview.html into jdk.jdi
> module-info.java [2]
> * JDK-8178038 Copy jdwp-protocol.html to proper location [3]
> * JDK-8178039 Copy jvmti.html to proper location [4]
>
> I hope JDK-8178043 captures the intent of the solution I understand that
> Mark and Jon seemed to agree upon.

Yes, I think it does.  Thanks for filing it.

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

Re: RFR: JDK-8172312 Update docs target and image for new combined docs

Jonathan Gibbons
In reply to this post by Magnus Ihse Bursie
Magnus, Mark,

Don't we need the JEP to be moved from "Proposed To Target" to
"Targetted" before we can push?

-- Jon

On 04/04/2017 04:47 AM, Magnus Ihse Bursie wrote:

> Here is an updated webrev:
> http://cr.openjdk.java.net/~ihse/JDK-8172312-combined-javadocs/webrev.03
>
> The only change compared to the previous webrev is that I have updated
> the title for the JDK javadocs so it does not claim to be Java SE.
>
> I have filed the following follow-up bugs to address Mark's concerns,
> and concerns expressed elsewhere:
>
> * JDK-8178043 Group Java SE, JDK and JavaFX modules in unified javadoc
> [1]
> * JDK-8178037 Move information from jdi-overview.html into jdk.jdi
> module-info.java [2]
> * JDK-8178038 Copy jdwp-protocol.html to proper location [3]
> * JDK-8178039 Copy jvmti.html to proper location [4]
>
> I hope JDK-8178043 captures the intent of the solution I understand
> that Mark and Jon seemed to agree upon.
>
> I also refer to the previously existing:
>
> * JDK-8175824 Provide more flexible means for setting the overview
> text in the generated docs [5]
>
> which I have amended with the task of also making sure that the values
> of the title text snippets gets proper values.
>
> Since a lot of the continued work on Javadoc changes in JDK 9 is
> dependent on this change, I hope it is now clear for pushing.
>
> /Magnus
>
> [1] https://bugs.openjdk.java.net/browse/JDK-8178043
> [2] https://bugs.openjdk.java.net/browse/JDK-8178037
> [3] https://bugs.openjdk.java.net/browse/JDK-8178038
> [4] https://bugs.openjdk.java.net/browse/JDK-8178039
> [5] https://bugs.openjdk.java.net/browse/JDK-8175824
>
>
> On 2017-04-04 01:38, [hidden email] wrote:
>> 2017/4/3 3:24:52 -0700, [hidden email]:
>>> I think the distinction you ask for is already there. The two separate
>>> make targets "docs-javadoc" and "docs-reference" builds two distinct
>>> images "docs" and "javase-docs", respectively. The first of these
>>> builds
>>> the complete Java SE + JDK documentation, the second build just the
>>> Java
>>> SE documentation.
>> I'm glad that there's an SE-only target, but that's not what I asked
>> for.
>>
>>> I do not think it's a good idea to go further and actually *remove* the
>>> Java SE part from the complete "docs" image.
>> That's not what I asked for, either.  I suggested making a stronger
>> distinction between the specifications of the SE APIs and those of the
>> rest of the JDK, by putting the latter in a subdirectory of the same
>> image.  Sorry if that wasn't clear.
>>
>>> Upholding such a formal
>>> difference between different parts of the JDK is likely to be just
>>> confusing to common Java developers. I believe that enforcing such a
>>> cut
>>> would eliminate much of the work that has been put into giving the the
>>> Java developer community a unified access to all releveant
>>> documentation.
>> I see your point, but failing to make a strong distinction could also
>> confuse developers, since it may lead some to use JDK-specific APIs when
>> they really want to write code that's portable to any SE implementation.
>>
>> Still, there may be better ways to make that distinction, as Jon
>> suggests
>> nearby.
>>
>>> With that said, we should change the heading so that only the
>>> javase-docs image claims to be the SE specification.
>> Yes, we must do that, at a bare minimum.
>>
>> - Mark
>

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

Re: RFR: JDK-8172312 Update docs target and image for new combined docs

Magnus Ihse Bursie

On 2017-04-04 21:28, Jonathan Gibbons wrote:
> Magnus, Mark,
>
> Don't we need the JEP to be moved from "Proposed To Target" to
> "Targetted" before we can push?
I would have assumed that since the patch itself has been code reviewed,
and follows the "noreg-doc" rule, it would be fair game to push,
regardless of it's relation to a JEP (that covers many other
documentation issues). But then again, I'm no expert in these procedural
questions.

/Magnus

>
> -- Jon
>
> On 04/04/2017 04:47 AM, Magnus Ihse Bursie wrote:
>> Here is an updated webrev:
>> http://cr.openjdk.java.net/~ihse/JDK-8172312-combined-javadocs/webrev.03
>>
>> The only change compared to the previous webrev is that I have
>> updated the title for the JDK javadocs so it does not claim to be
>> Java SE.
>>
>> I have filed the following follow-up bugs to address Mark's concerns,
>> and concerns expressed elsewhere:
>>
>> * JDK-8178043 Group Java SE, JDK and JavaFX modules in unified
>> javadoc [1]
>> * JDK-8178037 Move information from jdi-overview.html into jdk.jdi
>> module-info.java [2]
>> * JDK-8178038 Copy jdwp-protocol.html to proper location [3]
>> * JDK-8178039 Copy jvmti.html to proper location [4]
>>
>> I hope JDK-8178043 captures the intent of the solution I understand
>> that Mark and Jon seemed to agree upon.
>>
>> I also refer to the previously existing:
>>
>> * JDK-8175824 Provide more flexible means for setting the overview
>> text in the generated docs [5]
>>
>> which I have amended with the task of also making sure that the
>> values of the title text snippets gets proper values.
>>
>> Since a lot of the continued work on Javadoc changes in JDK 9 is
>> dependent on this change, I hope it is now clear for pushing.
>>
>> /Magnus
>>
>> [1] https://bugs.openjdk.java.net/browse/JDK-8178043
>> [2] https://bugs.openjdk.java.net/browse/JDK-8178037
>> [3] https://bugs.openjdk.java.net/browse/JDK-8178038
>> [4] https://bugs.openjdk.java.net/browse/JDK-8178039
>> [5] https://bugs.openjdk.java.net/browse/JDK-8175824
>>
>>
>> On 2017-04-04 01:38, [hidden email] wrote:
>>> 2017/4/3 3:24:52 -0700, [hidden email]:
>>>> I think the distinction you ask for is already there. The two separate
>>>> make targets "docs-javadoc" and "docs-reference" builds two distinct
>>>> images "docs" and "javase-docs", respectively. The first of these
>>>> builds
>>>> the complete Java SE + JDK documentation, the second build just the
>>>> Java
>>>> SE documentation.
>>> I'm glad that there's an SE-only target, but that's not what I asked
>>> for.
>>>
>>>> I do not think it's a good idea to go further and actually *remove*
>>>> the
>>>> Java SE part from the complete "docs" image.
>>> That's not what I asked for, either.  I suggested making a stronger
>>> distinction between the specifications of the SE APIs and those of the
>>> rest of the JDK, by putting the latter in a subdirectory of the same
>>> image.  Sorry if that wasn't clear.
>>>
>>>> Upholding such a formal
>>>> difference between different parts of the JDK is likely to be just
>>>> confusing to common Java developers. I believe that enforcing such
>>>> a cut
>>>> would eliminate much of the work that has been put into giving the the
>>>> Java developer community a unified access to all releveant
>>>> documentation.
>>> I see your point, but failing to make a strong distinction could also
>>> confuse developers, since it may lead some to use JDK-specific APIs
>>> when
>>> they really want to write code that's portable to any SE
>>> implementation.
>>>
>>> Still, there may be better ways to make that distinction, as Jon
>>> suggests
>>> nearby.
>>>
>>>> With that said, we should change the heading so that only the
>>>> javase-docs image claims to be the SE specification.
>>> Yes, we must do that, at a bare minimum.
>>>
>>> - Mark
>>
>

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

Re: RFR: JDK-8172312 Update docs target and image for new combined docs

mark.reinhold
In reply to this post by Jonathan Gibbons
2017/4/4 12:28:18 -0700, [hidden email]:
> Don't we need the JEP to be moved from "Proposed To Target" to
> "Targetted" before we can push?

Yep.  Coming right up ...

- Mark
Loading...