[Doc]Request to fix SI-9009 : Combine ScalaDoc with companion

[Justin Pihony]

All,

    I would like to fix the issue: Combine companion object documentation with trait/class page. There is no concrete solution, though. So, the biggest question for me is how to set it up. My proposal would be to keep everything the same and just add a companion section after each normal section:

Instance constructors

Type Members

Type Members (from companion [object/class/trait])

Abstract Value Members

Abstract Value Members (from companion [object/class/trait])

.....

Thanks,

Justin

[Jason Zaugg]

Hi Justin,

Thanks for taking a look at this issue.

We'll also need to find a way to present the class/object level documentation from both, as well as the signatures of class and object. Something along the lines of:

Class Signature
Class Doc
Object Signature
Object Doc
(expanded member filters to show/hide class/object members)
(member sections as per your proposal)

​

I suppose the alternative would be to more or less concatenate the layouts of the current class and object pages. 

Perhaps you could create a mock-up of both options? Having something visual will help to find what people find the best presentation.

-jason

[Justin Pihony]

I'll provide a few mockups and post them back here. I am of the persuasion that putting the companion signature and documentation would end up being too cluttered. The user could still go to the companion documentation for those details. Gaining the member signatures seems like the biggest benefit for this change?

[Justin Pihony]

Below are some links on possible solutions. If you get any odd formatting or 404's, then just wait a little as Google Drive seems to still be sharing parts of the files.

• My original proposal. No top level comments, only member definitions.
• Counter-proposal to my original. Include top level comments
• Top level comments included. They are split for aesthetics.
• Top level comments included. They are split for aesthetics and companion toggled off by default

The companion member headers are listed as [Header] Companion for now, but the wording obviously will need to be tweaked. Also, the last link with the toggle needs to have the toggle arrow on the same line as the signature. These are all rough edges that I will fix, but for now I just wanted to put the general set up out there for review. I personally am still leaning towards my original proposal as I think the top level data is not as important to duplicate as the definition. Otherwise, I think the last link isn't too bad as it hides the companion top level comments by default. Let me know what you think is best and I can go ahead and begin ironing out the rough edges.

Thanks,

Justin

[Justin Pihony]

Does anybody have any strong opinions on either one of these?

Thanks,

Justin

[Adriaan Moors]

Hi Justin,

I followed those links but it wasn't clear to me where to look for the differences. Maybe it would be easier to comment on screenshots that illustrate the different designs?

cheers

adriaan

--
You received this message because you are subscribed to the Google Groups "scala-internals" group.
To unsubscribe from this group and stop receiving emails from it, send an email to scala-interna...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Justin Pihony]

Sure! Here is a new link so as to not inundate you with images directly. I included a screenshot of the members split, however that is the same across all the choices. The point in question is with regards to the top level documentation only.

Thanks,

Justin

[Vlad Ureche]

I like the second one best, ideally with a button next to the object saying "Jump to object".

HTH,

Vlad

[Vlad Ureche]

2015-02-23 21:01 GMT+01:00 Vlad Ureche <vlad....@gmail.com>:

I like the second one best, ideally with a button next to the object saying "Jump to object".

And without the companion object documentation at all, that belongs to its own page.

Vlad

[Justin Pihony]

That would actually be a new option that I had not created. I think that wouldn't be too bad :)  An example would be something like:

Class Signature

Companion Signature      [Jump to Companion Documentation]

-----

Class Documentation

In writing this though, should this be right at the top when MOST of the documentation is now concatenated. Maybe different wording for the Jump to button?

--
You received this message because you are subscribed to a topic in the Google Groups "scala-internals" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/scala-internals/BAF1VjgeUPo/unsubscribe.
To unsubscribe from this group and all its topics, send an email to scala-interna...@googlegroups.com.

[Adriaan Moors]

Thanks for putting together the screenshots!

I also prefer having the companion accompany the class, though it should not take too much space. 

Once we've converged on a couple of options, maybe you could also ask over at scala-language/scala-user what people think? Would be good to get some fresh (to Scala) eyes on this.

--

[Justin Pihony]

As there isn't a lot of voice on this here, should I just take all the options to the scala-user list? There aren't that many that it should cause a problem with choice.

Justin

[Adriaan Moors]

On Fri, Feb 27, 2015 at 10:47 AM, Justin Pihony <justin...@gmail.com> wrote:

As there isn't a lot of voice on this here, should I just take all the options to the scala-user list?

Sorry about that -- please do.

[Justin Pihony]

Posted -> https://groups.google.com/forum/#!topic/scala-user/8sPhm1jVEr0

[Justin Pihony]

I have now posted on both scala-users and scala-debate. Nobody seems to be able to reach a consensus, so I am now asking if the second option, but without the companion documentation (so just the companion signature), would be accepted in a PR? Otherwise, what, if any suggestion should I go with?

Justin

[Simon Ochsenreither]

I think the issue is that the class documentation is often very cluttered already (due to long inheritance chains) and intimidating for beginners. Imho it would make sense to make the link in the top right corner even more prominent: Maybe we could use the color of the companion objects header (blue) and turn one third of the top into a huge link?