Scaladoc request; hide nonpublic classes in sidebar, when appropriate

This would mean we need to teach the side bar some more filtering tricks.

I'd say feel free to open a ticket for this, as it doesn't sound too
unreasonable. But I'm no committer, so I can't guarantee for anything.
;-)

Regards,
Rüdiger

2011/5/20 Ken McDonald :
> One feature I very much like about Scaladoc is that when it is set to show
> only "Public" API, only public methods and fields are displayed; exactly
> what is needed to keep a user of my API from being overwhelmed. However,
> non-public classes and traits still show up in the sidebar, and unless there
> is a really compelling reason for keeping them there, I'd like to suggest
> that they also be hidden when Public is turned on. It's common for a user to
> begin investigating an API by picking a likely-looking class to browse, and
> allowing them to browse classes that are only for internal use is really not
> very useful.
> In the meantime, are there any tricks I can use to prevent non-public
> classes from showing up in the sidebar?
> Thanks,
> Ken

There's a counterpart to this. Objects, traits and classes that are
inside some other object, trait or class don't show up on the sidebar
at all. Sometimes they are rather important, such as Parsers (the
trait).Parser (and quite a few other type members of Parsers), or
Regex (the object).Match.

I have absolutely no idea how to display them, but if someone's going
to make changes to the sidebar, this would be a matter to consider as
well.

On Sat, May 21, 2011 at 11:53, Ruediger Keller wrote:
> This would mean we need to teach the side bar some more filtering tricks.
>
> I'd say feel free to open a ticket for this, as it doesn't sound too
> unreasonable. But I'm no committer, so I can't guarantee for anything.
> ;-)
>
> Regards,
> Rüdiger
>
>
> 2011/5/20 Ken McDonald :
>> One feature I very much like about Scaladoc is that when it is set to show
>> only "Public" API, only public methods and fields are displayed; exactly
>> what is needed to keep a user of my API from being overwhelmed. However,
>> non-public classes and traits still show up in the sidebar, and unless there
>> is a really compelling reason for keeping them there, I'd like to suggest
>> that they also be hidden when Public is turned on. It's common for a user to
>> begin investigating an API by picking a likely-looking class to browse, and
>> allowing them to browse classes that are only for internal use is really not
>> very useful.
>> In the meantime, are there any tricks I can use to prevent non-public
>> classes from showing up in the sidebar?
>> Thanks,
>> Ken
>

Hello Ken.
I am astonished about that. In the quick test I just did, all private classes (inner private, and package private) are not in the sidebar. In fact, no documentation is generated for them at all. Could you be more precise as to the situation you are experiencing.
Cheers,Gilles.

Yes, you're quite correct, but you'll notice in my original post I said "non-public" members, not "private" members. In other words, protected classes, and these are displayed when "Public" is turned on.
Now I can see two different use cases for this that slants the argument one way or another. One case says that "protected" should be displayed because the API might be extended through inheritance, and so this is really "public" information. The other case is that classes are declared "protected" in the package because they serve as base classes for other package classes which are the public classes; this is the situation I'm in. I have a bunch of protected classes that I don't want to be seen by users of my API because they have no use for them.
I could try to do some reorg to figure out a way to accomplish this--it's not high on my list of priorities right now. I was just really suprised to find that the "public" setting exposes classes which are not public by the definitions I'm used to.
Thanks,Ken

Shouldn't you then declare the classes as package private?

On Tue, May 24, 2011 at 17:50, Ken McDonald wrote:
> Yes, you're quite correct, but you'll notice in my original post I said
> "non-public" members, not "private" members. In other words, protected
> classes, and these are displayed when "Public" is turned on.
> Now I can see two different use cases for this that slants the argument one
> way or another. One case says that "protected" should be displayed because
> the API might be extended through inheritance, and so this is really
> "public" information. The other case is that classes are declared
> "protected" in the package because they serve as base classes for other
> package classes which are the public classes; this is the situation I'm in.
> I have a bunch of protected classes that I don't want to be seen by users of
> my API because they have no use for them.
> I could try to do some reorg to figure out a way to accomplish this--it's
> not high on my list of priorities right now. I was just really suprised to
> find that the "public" setting exposes classes which are not public by the
> definitions I'm used to.
> Thanks,
> Ken

Probably, now that I know to do that. I keep forgetting how rich the scala access mechanisms are.
Thanks,Ken

In general, I think there are three different audiences for API documentation in class-based languages:

. Users of the API classes (public documentation).
. Extenders of the classes (protected).
. Implementers (private).

It would be nice to have all three settings available.

A

On Tue, May 24, 2011 at 3:04 PM, Ken McDonald <ykkenmcd@gmail.com> wrote:

Probably, now that I know to do that. I keep forgetting how rich the scala access mechanisms are.
Thanks, Ken

#avg_ls_inline_popup{position: absolute;z-index: 9999;padding: 0px 0px;margin-left: 0px;margin-top: 0px;overflow: hidden;word-wrap: break-word;color: #000;font-size: 10px;text-align: left;line-height: 130%;}