RFR: 8159305: Enhance the javadoc tool to support module related options

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

RFR: 8159305: Enhance the javadoc tool to support module related options

Kumar Srinivasan
Reply | Threaded
Open this post in threaded view
|

Re: RFR: 8159305: Enhance the javadoc tool to support module related options

Martin Buchholz-3
Hi Kumar,

Is this intended to address the jsr166 use case (source files belong to a module, but not the entire module is being processed, and not all module sources are in a single tree)?

Currently, jsr166 CVS docs are still broken. "ant docs" fails with

  [javadoc] java.lang.AssertionError
  [javadoc] at com.sun.tools.javac.util.Assert.error(jdk.compiler@9-ea/Assert.java:155)
  [javadoc] at com.sun.tools.javac.util.Assert.checkNull(jdk.compiler@9-ea/Assert.java:54)
  [javadoc] at com.sun.tools.javac.code.Symtab.enterModule(jdk.compiler@9-ea/Symtab.java:755)
  [javadoc] at com.sun.tools.javac.comp.Modules.enterModule(jdk.compiler@9-ea/Modules.java:262)
  [javadoc] at com.sun.tools.javac.comp.Modules.enterModules(jdk.compiler@9-ea/Modules.java:240)
  [javadoc] at com.sun.tools.javac.comp.Modules.enter(jdk.compiler@9-ea/Modules.java:208)
  [javadoc] at com.sun.tools.javac.main.JavaCompiler.readSourceFile(jdk.compiler@9-ea/JavaCompiler.java:816)
  [javadoc] at com.sun.tools.javac.main.JavaCompiler.readSourceFile(jdk.compiler@9-ea/JavaCompiler.java:778)
  [javadoc] at com.sun.tools.javac.main.JavaCompiler.access$100(jdk.compiler@9-ea/JavaCompiler.java:97)
  [javadoc] at com.sun.tools.javac.main.JavaCompiler$1.complete(jdk.compiler@9-ea/JavaCompiler.java:339)
  [javadoc] at com.sun.tools.javac.code.ClassFinder.fillIn(jdk.compiler@9-ea/ClassFinder.java:362)
  [javadoc] at com.sun.tools.javac.code.ModuleFinder.lambda$findSingleModule$0(jdk.compiler@9-ea/ModuleFinder.java:206)
  [javadoc] at com.sun.tools.javac.code.Symbol.complete(jdk.compiler@9-ea/Symbol.java:602)
  [javadoc] at com.sun.tools.javac.comp.Modules.setCompilationUnitModules(jdk.compiler@9-ea/Modules.java:366)
  [javadoc] at com.sun.tools.javac.comp.Modules.enter(jdk.compiler@9-ea/Modules.java:210)
  [javadoc] at jdk.javadoc.internal.tool.JavadocTool.getEnvironment(jdk.javadoc@9-ea/JavadocTool.java:190)
  [javadoc] at jdk.javadoc.internal.tool.Start.parseAndExecute(jdk.javadoc@9-ea/Start.java:405)
  [javadoc] at jdk.javadoc.internal.tool.Start.begin(jdk.javadoc@9-ea/Start.java:299)
  [javadoc] at jdk.javadoc.internal.tool.Start.begin(jdk.javadoc@9-ea/Start.java:243)
  [javadoc] at jdk.javadoc.internal.tool.Main.execute(jdk.javadoc@9-ea/Main.java:63)
  [javadoc] at jdk.javadoc.internal.tool.Main.main(jdk.javadoc@9-ea/Main.java:52)
  [javadoc] javadoc: error - fatal error


On Mon, Jun 20, 2016 at 4:18 PM, Kumar Srinivasan <[hidden email]> wrote:
Hello,

Please review the changes to fix:
https://bugs.openjdk.java.net/browse/JDK-8159305

The webrev is here:
http://cr.openjdk.java.net/~ksrini/8159305/webrev.00/

The spec-diff is here for reference:
http://cr.openjdk.java.net/~ksrini/8159305/spec-diff/overview-summary.html


Thanks
Kumar


Reply | Threaded
Open this post in threaded view
|

Re: RFR: 8159305: Enhance the javadoc tool to support module related options

Kumar Srinivasan
Hi Martin,

No this does address the 166 issues, bug still open,
https://bugs.openjdk.java.net/browse/JDK-8152911

This enhancement, makes it easy for folks to generate javadocs
in a module centric manner.

To give you an example, in the existing tool, you would do something like
-modulesourcepath some-paths
java.lang java.util java.io  ....
ie. packages that constitutes  the module java.base

So now with these enhancements you can simply do this:
-modulesourcepath somepaths
--module java.base --expand-requires:public

Which will walk the module-graph documenting those modules
and packages that meet the criteria.

HTH

Kumar



Hi Kumar,

Is this intended to address the jsr166 use case (source files belong to a module, but not the entire module is being processed, and not all module sources are in a single tree)?

Currently, jsr166 CVS docs are still broken. "ant docs" fails with

  [javadoc] java.lang.AssertionError
  [javadoc] at com.sun.tools.javac.util.Assert.error([hidden email])
  [javadoc] at com.sun.tools.javac.util.Assert.checkNull([hidden email])
  [javadoc] at com.sun.tools.javac.code.Symtab.enterModule([hidden email])
  [javadoc] at com.sun.tools.javac.comp.Modules.enterModule([hidden email])
  [javadoc] at com.sun.tools.javac.comp.Modules.enterModules([hidden email])
  [javadoc] at com.sun.tools.javac.comp.Modules.enter([hidden email])
  [javadoc] at com.sun.tools.javac.main.JavaCompiler.readSourceFile([hidden email])
  [javadoc] at com.sun.tools.javac.main.JavaCompiler.readSourceFile([hidden email])
  [javadoc] at com.sun.tools.javac.main.JavaCompiler.access$100([hidden email])
  [javadoc] at com.sun.tools.javac.main.JavaCompiler$1.complete([hidden email])
  [javadoc] at com.sun.tools.javac.code.ClassFinder.fillIn([hidden email])
  [javadoc] at com.sun.tools.javac.code.ModuleFinder.lambda$findSingleModule$0([hidden email])
  [javadoc] at com.sun.tools.javac.code.Symbol.complete([hidden email])
  [javadoc] at com.sun.tools.javac.comp.Modules.setCompilationUnitModules([hidden email])
  [javadoc] at com.sun.tools.javac.comp.Modules.enter([hidden email])
  [javadoc] at jdk.javadoc.internal.tool.JavadocTool.getEnvironment([hidden email])
  [javadoc] at jdk.javadoc.internal.tool.Start.parseAndExecute([hidden email])
  [javadoc] at jdk.javadoc.internal.tool.Start.begin([hidden email])
  [javadoc] at jdk.javadoc.internal.tool.Start.begin([hidden email])
  [javadoc] at jdk.javadoc.internal.tool.Main.execute([hidden email])
  [javadoc] at jdk.javadoc.internal.tool.Main.main([hidden email])
  [javadoc] javadoc: error - fatal error


On Mon, Jun 20, 2016 at 4:18 PM, Kumar Srinivasan <[hidden email]> wrote:
Hello,

Please review the changes to fix:
https://bugs.openjdk.java.net/browse/JDK-8159305

The webrev is here:
http://cr.openjdk.java.net/~ksrini/8159305/webrev.00/

The spec-diff is here for reference:
http://cr.openjdk.java.net/~ksrini/8159305/spec-diff/overview-summary.html


Thanks
Kumar



Reply | Threaded
Open this post in threaded view
|

Re: RFR: 8159305: Enhance the javadoc tool to support module related options

Jonathan Gibbons
In reply to this post by Kumar Srinivasan


On 06/20/2016 04:18 PM, Kumar Srinivasan wrote:

> Hello,
>
> Please review the changes to fix:
> https://bugs.openjdk.java.net/browse/JDK-8159305
>
> The webrev is here:
> http://cr.openjdk.java.net/~ksrini/8159305/webrev.00/
>
> The spec-diff is here for reference:
> http://cr.openjdk.java.net/~ksrini/8159305/spec-diff/overview-summary.html 
>
>
>
> Thanks
> Kumar
>

DocletEnvironment: general  changes will require a CCC.

DocletEnvironment:61

"annotations" is wrong.   You mean "annotation types".  An "annotation"
is the *use* of an annotation type.

line 101, don't like the "style" of plural type names (like
"ModuleElements") in plain text. Type names should be in {@code} font.  
Consider using the underlying English words. (module elements, package
elements, etc). If in doubt, follow whatever style Joe uses in the 269 API.

linbe 142. terse

doclet/package-info:63 plural type names again
Should use code form for any occurrence of an option name

60/61 the name is "included" but the <em> term is "specified". Not good
to be inconsistent.
89 uses both, I'm not usre if the two are the same or different.


AbstractExecutableMemberWriter, 118, who is "we"?  Could improve
phrasing, but I accept it's internal API.


AnnotationTypeRequiredMemberImpl, 108, OK, itr's an overloaded method,
but I simply note that in this override, the parameter is ignored.


ConfigurationImpl 422
replace    DocPath.empty.resolve with plain old "new DocPath"

AbstractDoclet 119
Uugh

Configuration 358
Bad grammar/punctuation.   I'm surprised by the ordering of the decls
for modules and modulePackages. I would have thought that modules is the
dominant declaration here, and the modulePackages is derived from
modules;  instead, the comment makes it seem like it's the other way
around.  And, according to the code in initModules, the description is
wrong anyway.

Configuration 392, initModules, similar to preceding comment. I think
you have the role of modules and modulePackages backwards. Create
"modules" first, add in the specifiedModules, then add in the packages.

Configuration 420, why the guard, are you worried about calling this
multiple times?

TypeElementCatalog 103, redundant TypeELementCatalog.this (looks like NB
error)

Utils is a bit of a mess, taken in conjunction with Configuration.
There's a no-reason split between stuff in Utils and stuff in Configuration.

DocEnv
funky imports order

DocEnv.ModulePackage  ... an interface? really?   why not just a class
containing two public final strings?

JavadocTool ... IncludesTable looks big enough to be split into its own
top level class, and *maybe* should start becoming the basis of a new
abstraction for all "included" stuff on the command, i.e. superseding
code from Configuration and Utils.

JavadocTool.IncludesTable.ModulePackage. Over-engineered.

RootDocImpl:
more lack of abstraction with regard to stuff specified on the command line.

ToolOption
add M as an alias for MODULE

New long form options (SHOW_MODULES, etc) use space or = as a separator,
not :

ToolOption.AccessHelper looks misguided.  Either the functionality here
should be merged into Helper, or it should possibly be renamed and
become a member of Helper that supersedes/replaces the showAccess map
in  Helper.

-- Jon