Re: RFR: 8154399, 8159096, export packages containing standard javadoc doclet

[Mandy Chung]

> On Jun 16, 2016, at 7:28 PM, Jonathan Gibbons  
> wrote:
> 
> Please review this simple fix for two related aspects of the same problem:
> 
> Export the "standard doclet" used by javadoc, such that it is possible to 
> derive alternative doclets, either by delegation or subtyping.
> 
> In JDK 9, javadoc has a "new" standard doclet (JEP 221), but the old one 
> remains for compatibility, for the time being. Both should be exported.
> 
> 
> Jigsaw folk:
>Please review the changes to jdk.javadoc module-info.
> 
> Build folk:
>The javadoc documentation is extended to include the documentation for the 
> package containing the new StandardDoclet.
>(The API for the old StandardDoclet was never published in this manner; it 
> is only included in the javadoc tool guide, which remains unchanged, for now.)
> 
> javadoc folk:
>The top level class for the new StandardDoclet is moved, without any 
> functional change, from an internal package to the new exported package.
> 
> JBS: https://bugs.openjdk.java.net/browse/JDK-8154399
> https://bugs.openjdk.java.net/browse/JDK-8159096
> Webrev: http://cr.openjdk.java.net/~jjg/8154399/webrev.00


Looks fine to me.  

I’m sure you have considered the name of the new package is only one-character 
difference than jdk.javadoc.doclet.  Just wonder what the relationale is behind 
why the new StandardDoclet class is in a new package rather than in 
jdk.javadoc.doclet?

Mandy

RFR: 8154399, 8159096, export packages containing standard javadoc doclet

[Jonathan Gibbons]

Please review this simple fix for two related aspects of the same problem:

Export the "standard doclet" used by javadoc, such that it is possible 
to derive alternative doclets, either by delegation or subtyping.


In JDK 9, javadoc has a "new" standard doclet (JEP 221), but the old one 
remains for compatibility, for the time being. Both should be exported.



Jigsaw folk:
Please review the changes to jdk.javadoc module-info.

Build folk:
The javadoc documentation is extended to include the documentation 
for the package containing the new StandardDoclet.
(The API for the old StandardDoclet was never published in this 
manner; it is only included in the javadoc tool guide, which remains 
unchanged, for now.)


javadoc folk:
The top level class for the new StandardDoclet is moved, without 
any functional change, from an internal package to the new exported package.


JBS: https://bugs.openjdk.java.net/browse/JDK-8154399
https://bugs.openjdk.java.net/browse/JDK-8159096
Webrev: http://cr.openjdk.java.net/~jjg/8154399/webrev.00

-- Jon

Re: 8159248: ModuleFinder.of spec + 8158456: ModuleDescriptor.read does not verify dependence on java.base

[Alan Bateman]

On 16/06/2016 19:11, Mandy Chung wrote:

On Jun 16, 2016, at 9:44 AM, Alan Bateman  wrote:

On 16/06/2016 17:31, Mandy Chung wrote:


:
ModuleFinder.of spec describes the possible cases where FindException may be 
thrown by a module finder’s find or findAll methods.

It would be useful to have the @throws FindException if an error occurs finding 
all modules in find and findAll methods to link to such description.

My concern with this is that it will clutter the @throws description if we 
attempt to link to all cases (there are too many).

One idea is to add section header in ModuleFinder.of error cases and then
@throws FindException if an error occurs finding modules, as described in ModuleFinder::of


I'll think about it but ModuleFinder.of is just one implementation.

-Alan

Re: 8159248: ModuleFinder.of spec + 8158456: ModuleDescriptor.read does not verify dependence on java.base

[Alan Bateman]

On 16/06/2016 17:47, Paul Benedict wrote:

Please definitely list all such possible exceptions. The knowledge 
outweighs concern for clutter, IMO. I'd rather know the full number of 
ways an API can fail rather than receive a failure that wasn't documented.
There is one exception and all the cases that we can describe are 
already in the javadoc. There are several other cases where we don't 
fail but should, to address those requires several adjustments to the 
builder API and I'd prefer to keep that separate.


-Alan

Re: 8159248: ModuleFinder.of spec + 8158456: ModuleDescriptor.read does not verify dependence on java.base

[Paul Benedict]

Please definitely list all such possible exceptions. The knowledge
outweighs concern for clutter, IMO. I'd rather know the full number of ways
an API can fail rather than receive a failure that wasn't documented.

Cheers,
Paul

On Thu, Jun 16, 2016 at 11:44 AM, Alan Bateman 
wrote:

> On 16/06/2016 17:31, Mandy Chung wrote:
>
> :
>> ModuleFinder.of spec describes the possible cases where FindException may
>> be thrown by a module finder’s find or findAll methods.
>>
>> It would be useful to have the @throws FindException if an error occurs
>> finding all modules in find and findAll methods to link to such description.
>>
> My concern with this is that it will clutter the @throws description if we
> attempt to link to all cases (there are too many).
>
>
>> As I commented offline, it’d be good to link to the definition of legal
>> package name but looks like we need to add that in some appropriate spec
>> before we can do that.
>>
>> There is big overhaul of the builder API needed and I think that is the
> right place to do this. The javadoc update here deliberately delegates to
> avoid repeating everything.
>
> -Alan
>

Re: 8159248: ModuleFinder.of spec + 8158456: ModuleDescriptor.read does not verify dependence on java.base

[Alan Bateman]

On 16/06/2016 17:31, Mandy Chung wrote:


:
ModuleFinder.of spec describes the possible cases where FindException may be 
thrown by a module finder’s find or findAll methods.

It would be useful to have the @throws FindException if an error occurs finding 
all modules in find and findAll methods to link to such description.
My concern with this is that it will clutter the @throws description if 
we attempt to link to all cases (there are too many).




As I commented offline, it’d be good to link to the definition of legal package 
name but looks like we need to add that in some appropriate spec before we can 
do that.

There is big overhaul of the builder API needed and I think that is the 
right place to do this. The javadoc update here deliberately delegates 
to avoid repeating everything.


-Alan

Re: 8159248: ModuleFinder.of spec + 8158456: ModuleDescriptor.read does not verify dependence on java.base

[Mandy Chung]

> On Jun 16, 2016, at 8:33 AM, Alan Bateman  wrote:
> 
> I need a Reviewer for a patch is to address two conformance issues.
> 
> One is that the ModuleFinder.of(Path...) javadoc doesn't make it clear that 
> an exception is thrown when a module descriptor cannot be created for an 
> automatic module. As part of this I've changed the implementation to not 
> silently skip services configuration files or contents that don't parse as 
> identifiers. Also a small change to ModuleDescriptor.Builder in preparation 
> for other changes.
> 
> The other issue is that the requires table in the Module attribute for 
> java.base should be empty and should have at least an entry for java.base for 
> other modules.
> 
> The changes are simple, most of the changes are extending the test coverage:
> 
> http://cr.openjdk.java.net/~alanb/8159248%2b8158456/webrev/

This looks fine.

ModuleFinder.of spec describes the possible cases where FindException may be 
thrown by a module finder’s find or findAll methods.

It would be useful to have the @throws FindException if an error occurs finding 
all modules in find and findAll methods to link to such description.

As I commented offline, it’d be good to link to the definition of legal package 
name but looks like we need to add that in some appropriate spec before we can 
do that.

Mandy

Re: 8159248: ModuleFinder.of spec + 8158456: ModuleDescriptor.read does not verify dependence on java.base

[Chris Hegarty]

> On 16 Jun 2016, at 16:33, Alan Bateman  wrote:
> 
> I need a Reviewer for a patch is to address two conformance issues.
> 
> One is that the ModuleFinder.of(Path...) javadoc doesn't make it clear that 
> an exception is thrown when a module descriptor cannot be created for an 
> automatic module. As part of this I've changed the implementation to not 
> silently skip services configuration files or contents that don't parse as 
> identifiers. Also a small change to ModuleDescriptor.Builder in preparation 
> for other changes.
> 
> The other issue is that the requires table in the Module attribute for 
> java.base should be empty and should have at least an entry for java.base for 
> other modules.
> 
> The changes are simple, most of the changes are extending the test coverage:
> 
> http://cr.openjdk.java.net/~alanb/8159248%2b8158456/webrev/

Both these changes look good to me Alan.

-Chris.

Re: Module in classpath

[Andrew Dinn]

On 15/06/16 17:12, Rémi Forax wrote:
> It is considered as a classical jar not a modular one. It's important
> because it enable backward compatibility without having to provide
> two jars.

Ok, so now the bonus question:

Does that mean that it is not possible to implement a Java JVMTI agent
as Jigsaw modularised code?

I'll add the following to render the question more specific: Clearly,
you can deploy an agent that links to related code deployed as a
companion module. I am thinking about the code included in the agent jar
itself i.e. the one passed to the -javaagent command line argument or to
the VM_Attach dynamic load API.

regards,


Andrew Dinn
---