Improve discoverability of methods in companion objects

[scabug]

Addendum to #9006, instead of merely making the links to companions more obvious, combine the trait/class and companion object into a single page with anchor tags to retain the current navigation but also improve the experience, allowing Ctrl-F to find a method on the page in either class/trait or companion, and also show the companion when simply browsing through the page.

[scabug]

Imported From: https://issues.scala-lang.org/browse/SI-9009?orig=1
Reporter: @dickwall
See #9006

[scabug]

@JustinPihony said:
Please see my thread on the internals mailing list for potential solutions.

[scabug]

@heathermiller said:
I argue that combining the top-level (or bits of other) documentation is not the best thing to do in the interest of clarity. As Ivano and others point out, the proposition having class & object signatures on the same page with methods from each merged into the same list greatly muddles things. I'd strongly advocate against it.

I actually don't think the desire/idea expressed in #9009 (list companion object members in their companion class/traits) is particularly good.

(Companion) objects are used differently than instances of classes. If the documentation makes it appear as if there are members on classes that don't really exist there, then more confusion is added to the mix down the road (and I do understand you're advocating for a second list at the bottom of the page). It allows people to continue operating without understanding the fundamental difference between classes and their companion objects.

My feeling is that if someone is frustrated because they can't find a member, and they're looking in the wrong place (e.g., class instead of companion object), we should help them learn the distinction between the two, so that in the future they know where to look.

• That said, I'd argue against the suggestion made in Improve discoverability of methods in companion objects #9009 altogether. Instead, I'd suggest that we do one or both of the following:
  Help people discover what companion objects are, maybe via a link to a doc on docs.scala-lang.org from within all ScalaDoc classes that have companion objects.
• If and only if a companion object exists which has 1 or more "apply" methods, generate a visually different entry in the list of constructors indicating something along the lines of, "it appears the companion object defines one or more apply factory methods. (The companion object could contain other factory methods as well.)", and link to the companion.

[scabug]

@heathermiller said:
Here's a concrete example of what I mean when I say usage is different. Consider factory method ofDim on companion object Array.

Let's say you have already instantiated an array called arr. You'll never try to do this: arr.ofDim. One would only ever try to use it this way Array.ofDim – for constructing an new array.

For that reason, I argue against listing ofDim on class Array's documentation page, even you generate this member in a list labeled "members from companion". It's confusing to people who know the difference between companion objects and classes – you don't want to go to class X and find methods listed there that you can't call on class X.

An additional problem I have with this – I suspect that if you combine companion object members with companion class/trait members, on the class/trait page, you'd be generating an awful lot of noise. Especially if some companion object contains many members.

[scabug]

@heathermiller said:
Verdict: (as per the mailing list discussion at https://groups.google.com/forum/#!topic/scala-debate/5s05bUsZ_rk)

I also think it's important not to muddle the difference between 
object and class. But how about we make an entry (say for class Seq) 
like this: 

Consult the companion object for members CanBuildFrom, ReUsableCF, 
apply, canBuildFrom, concat, empty, fill, iterate, newBuilder, range, 
tabulate, unapplySeq. 

We can make "companion object" and all listed names link to the proper 
definition and we can make a dual entry in the companion object. 

The advantage is that searching on the wrong page still leads to the 
right definition, and at the same time people would be straightened 
out about the difference. If we feel the list takes up too much space, 
we can make the font smaller. But at least there's a hint for the 
puzzled users. 

[scabug]

@SethTisue said:
Good discussion on the linked scala-debate thread. I agree that fully merging the class/trait and companion object pages is not desirable, but that other usability/discoverability improvements should be considered. I've renamed the ticket to reflect this.