I accept your use case, and there will be ways to generate docs for all
packages, not just exported ones.
And, it will be easy to distinguish exported packages from non-exported
packages on the module summary page.
So now we're just quibbling about a minor 3rd order RFE about the
headings in the left side frames, when the future of the left side
frames are themselves in doubt. That all being said, your comments and
suggestions are noted, and we'll take them into account when we come to
determine what, if anything, more should be done to these frames.
-- Jon
On 05/16/2016 10:22 AM, Paul Benedict wrote:
Jon, if you don't mind me arguing your assumption, I think most OSS
projects would want to generate their non-exported packages. There is
little reason you wouldn't want to with these projects. The power is
in the community to understand both the public and internal APIs. I
think this will be the default in the OSS world.
Now, I wouldn't expect non-exported packages for commercial/private
software, but that is a different matter.
Cheers,
Paul
On Mon, May 16, 2016 at 12:15 PM, Jonathan Gibbons
<[email protected] <mailto:[email protected]>> wrote:
Paul,
Generally speaking, you can translate "profiles" in JDK 8
documentation into "modules" for JDK 9 documentation.
And, I think you can assume that the default will be for javadoc
to only generate docs for exported packages, just as the default
is to generate docs for public/protected types, constructors and
members today. Yes, you'll be able to override the default, but
when you're generating the API documentation for the
users/consumers of a module, I would not expect non-exported
packages to be present.
In addition, there is some amount of discussion of the future role
of the frames on the left hand side. Given the availability of
the new Search feature in JDK 9, the utility of the indices on the
left hand side is significantly diminished. For example, if you
want to see the packages available in a module, you should be able
to search for the module name, bring up the module summary page,
and see which packages have been exported (always) and which are
not exported (if that info was requested when the docs were
generated.)
-- Jon
On 05/16/2016 09:48 AM, Paul Benedict wrote:
Jon, I actually think the precedent set is the "All Classes" and
"All Profiles" toggle link in the overview-frame.html (upper-left
frame) [1]. When "All Profiles" is clicked and then a profile,
you get an additional option of "All Packages" ... so you could
potentially add a fourth just for "Exported Packages"
PS: But I don't want to go through so many clicks :-) Having the
option listed immediately is preferable for my taste.
https://docs.oracle.com/javase/8/docs/api/
Cheers,
Paul
On Mon, May 16, 2016 at 11:40 AM, Jonathan Gibbons
<[email protected]
<mailto:[email protected]>> wrote:
I guess there's two aspects to this discussion:
1. The packages listed in the summary page for a module.
For this, my expectation is that it may be more significant
than just a CSS style.
For example, one possibility is that the packages could be
listed in a table with different "tabs" for
exported/non-exported packages, similar to the "table with
tabs" used to show different subsets of methods, such as here:
http://download.java.net/java/jdk9/docs/api/java/lang/Object.html
2. Other appearances of a package name.
Here, we would have to list the various places where a
package name could appear, and decide which if any should be
subject to special CSS styling. It has been instructive in
the design to look at the relationship between types and
packages to find a precedent for the relationship between
packages and modules. For example, I note there is no
special styling for package-private types compared to public
types.
-- Jon
On 05/16/2016 09:20 AM, Paul Benedict wrote:
Okay. Well, if it hasn't been planned, I definitely would
like to make a feature request. Specifically, a CSS style
for exported vs. nonexported packages so they can be
stylized differently.
Cheers,
Paul
On Mon, May 16, 2016 at 11:10 AM, Jonathan Gibbons
<[email protected]
<mailto:[email protected]>> wrote:
On 05/16/2016 07:52 AM, Paul Benedict wrote:
I was wondering if JavaDoc in JDK 9 provides any
visual indicator (color, format, textual output, or
otherwise) to indicate exported packages vs
non-exported packages?
Cheers,
Paul
javadoc is still a work in progress, and somewhat late
to the module game.
By default, javadoc should only show exported packages
for a module, the same way by default it only shows
public and protected constructors and members for a
class, but it should be able to show all packages, just
as it can show all constructors and members.
-- Jon
