Which packages are exported?

[Jonathan Gibbons]

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 
> <jonathan.gibbons at oracle.com <mailto:jonathan.gibbons at oracle.com>> 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
>>     <jonathan.gibbons at oracle.com
>>     <mailto:jonathan.gibbons at oracle.com>> 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
>>>         <jonathan.gibbons at oracle.com
>>>         <mailto:jonathan.gibbons at oracle.com>> 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
>>>
>>>
>>
>>
>
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20160516/60fa6fcf/attachment.html>