scaladoc: hiding of protected and private members can have poor usability

[coreyoconnor]

reproduction steps

Imagine you are trying to find how a method is available to a WordSpec in ScalaTest. A reasonable place to start is with the scaladoc for the wordspec trait:

• https://www.scalatest.org/scaladoc/3.2.0/org/scalatest/wordspec/AnyWordSpecLike.html

problem

This looks like complete documentation for the word spec trait: There are the asserts, extension methods for should, ignore, skip etc. For a customer using this API this looks like complete documentation.

Unfortunately, we've hit two difficulties:

1. Developers don't know that protected methods are hidden (See incomplete survey here )
2. The appropriate interface in this context is different than actual.

Discussion

I think the first difficulty can be resolved with a small change to UI.

The second tho: The conflict is from the different expectations of two use cases:

1. Using non-abstract classes from a library.
2. Extending classes and traits from a library.

For the first use case hiding protected members by default is expected. Users are neither expected nor able to use those methods. Discovering how a class works is aided by showing protected members but that isn't the default activity.

For the second use case showing (specific?) protected members by default is expected. Developers implementing subtypes will expect the API they use (which includes protected members) to be the presented API.

[SethTisue]

Developers don't know that protected methods are hidden

This is true of -private and private methods as well, as reported at #12217 (which I've closed as a duplicate)