Scala-dev: Issues and Ideas for Scaladoc

[felixmulder]

Ideas / General Issues

• [ ] When using multiple @see in docstrings, the order gets scrambled - should not happen. Same applies to @note
• [ ] Search the text of the doc comments in addition to the method names (TBD, not sure if feasible performance-wise)
• [ ] Make the EntityIterator in index.js switch between right and left by visibility instead of index
• [ ] Async all the things!
  
  
  
  • Tried this naively on writeFor methods, no performance gain, need to profile - crashed
  
  
• [ ] Auto-expand groups and hidden members on permalink or anchor click.
  
  
  
  • When a member is hidden by default, or by filter, and then selected via permalink or anchor click on page, the member must be shown to the user in the same manner as a visible member.
  
  
• [x] Differentiate between object_class_comp.svg and object_trait_comp.svg (fixed in: https://github.com/scala/scala/pull/5077)
• [x] When trying to expand the 'Full Signature' of a method that is shown as '[use case]', for example Option . max., the method body collapses (fixed in: https://github.com/scala/scala/pull/5077)
• [x] scala.Predef is missing from sidebar when browsing other scala.X entities (might be all objects without companion class/trait) (fixed in: https://github.com/scala/scala/pull/5077)
• [x] Predef extends ... needs to go away (sidebar)
• [x] In search results, place spacer before (c) instead of after. Also place (o) before (c) or (t). This'll make the search uniform to the sidebar (http://imgur.com/a/c1uyX) (fixed in: https://github.com/scala/scala/pull/5077)
• [x] Add type members to search in IndexScript.scala
• [x] Be able to navigate back to search results from a clicked search result entity
• [x] Fix regression where anchor-links don't highlight the target member
• [x] Fix anchor links mentioned here: https://github.com/scala/scala/pull/5018#issuecomment-195020665
• [x] Change behavior of "x"-button on input fields to only be removed if there is no input (changed from .on("blur", function () { ... }))
• [x] Remove Template.scala and other unused files
• [x] Remove dark bg on entity #definition
• [x] Remove unfold arrows in favor of highlighted left side
• [x] Unclutter contained classes (i.e. classes listed in package definition)
• [x] Hover-text on packages
• [x] Add sub-packages to side along with parent package of current entity for quick nav
• [x] Useful search result hover text use first sentence until the next point is added (https://github.com/scala/scala/pull/4978)
• [x] Add @shortDescription annotation for use with hover-text and short method summary
  StreamBuffer in Graphviz. Vlad says to instantiate a generator for each Graphviz

• [x] add some indicator that search is in progress

  Desktop issues

• [ ] Can't use Page Up / Page Down because of input keybindings

• [ ] Add @VladUreche's search from: https://github.com/scala/scala/pull/4912#issuecomment-183719491
• [ ] Keyboard navigation for members
• [x] Member indentation: https://github.com/scala/scala/pull/4912#issuecomment-183904610
  
  
  
  • Best bet is to refactor the docs to use a table element instead of an ordered list (solved by different behavior for mobile and desktop)
  
  
• [x] Clicking on a package doesn't open its doc
• [x] There's a triangle when on top of the modifiers when looking at the "Full Signature" (TraversableLike.foreach), see [3] https://github.com/scala/scala/pull/4912#issuecomment-184160480
• [x] Enable member filtering for types https://github.com/scala/scala/pull/4972
  

  Mobile Issues

General

• [ ] When rotating the phone to landscape the font becomes quite large (compare [1] and [2]) see https://github.com/scala/scala/pull/4912#issuecomment-184160480
• [ ] Unfolding the doc comment of TraversableOnce.reduceRight: the text is too large and overflow, not everything is readable
• [x] Remove auto-capitalization in input field (by: @lrytz)

• [x] There's no more get the abstract modifier (TraversableLike.foreach, package mutable) - is that by design?

  Android

• [x] On phones with large resolutions (1440x2560) method indentation is weird (should be fixed by https://github.com/scala/scala/pull/4912)

• [x] when entering the search box, the version number shows up again. it disappears when leaving the search box (Chrome)

  iOS

• [ ] Unfolding / folding the doc of a member requires two taps. the first seems to do what hovering does on the desktop version.

• [x] Down triangle is replaced by an emoji on iOS, use a glyph from the material icons font instead (already in scaladoc), when this is done - perhaps the layout of the member should be rethought to be more responsive
• [x] Jumpy scroll sometimes, sometimes only header moves (Safari & Chrome)
• [x] Some pages take a really long time to display - could be because of dropbox hosting (Chrome & Safari)
• [x] When clicking on a member, the page sometimes jumps to the top (Chrome & Safari)
• [x] Some page bodies are wider than the screen, for example "object Boolean" (@lrytz)

[jrudolph]

Here are a few more suggestions:

• add some indicator that search is in progress
• add keyboard shortcuts to jump to the search box (or if there already is a shortcut it should be discoverable)

[felixmulder]

@jrudolph: pressing tab should get you to the search field. Vlad wants Ctrl-F as well, will look into it :)

Regarding search in progress, it is feasible to inject a function to be run by the scheduler on search start. So should be able to do that :+1: Good idea!

[jrudolph]

Here's another small thing I noticed:

When you search something, then use the scroll-bar to scroll down and then try to use the arrow keys, you will select entities which are currently not visible. The selected element will not be scrolled into view until you managed to select an element which is visible.

This could be fixed in different ways. The simplest solution would be to just scroll the selected element into view. If you had nothing selected before this would make the view jump to the top, unfortunately. I wonder if it would be more sensible to always select the first element in the view, instead, when you hit whenever the previously selected element was not visible (other way round for ) .

[jrudolph]

Related: if you hit when the selection is currently on the left side on an entity and you also got lots of method results, the view seems to jump down arbitrarily.

I guess this is because the unit on the right hand side is just chosen to have the same index as the entity on the left hand side. As there's no relationship between elements with the same index on the left and the right side it would make more sense to select an element on the right side by visual position than by indexing into the result array.

[felixmulder]

I'll answer this in depth later - but pretty much there's an iterator for both sides with a switch function to toggle between the two. Where the new index is the min between length and index :)

[felixmulder]

@jrudolph: I snuck a fix for this:

When you search something, then use the scroll-bar to scroll down and then try to use the arrow keys, you will select entities which are currently not visible. The selected element will not be scrolled into view until you managed to select an element which is visible.

into https://github.com/scala/scala/pull/4983 :+1:

When it comes to this:

I guess this is because the unit on the right hand side is just chosen to have the same index as the entity on the left hand side. As there's no relationship between elements with the same index on the left and the right side it would make more sense to select an element on the right side by visual position than by indexing into the result array.

You're totally right, when switching between sides - it tries to match indices, but sometimes you might have multiple method matches in the right side for every entity match on the left. What you're proposing is the better fix. I'm adding it to the list up top. M4 is reportedly coming on the 27th, this might not make it into M4, but I'll be sure to fix it before the final release of 2.12.0 :) Thanks for all the feedback!

[jrudolph]

I snuck a fix for this:

Cool :)

No urgency from my side to fix those things.

[jrudolph]

Two things in the latest merged version:

• some text overlap:

• is there a way to specify the initial package? If you start at index.html it will now show the docs of the empty root package which is probably the most boring landing page you could think of. It seems scala-library and scala-compiler have put something there but this seems more like a hack than a real solution. (E.g. what happens if you want to merge several documentation packages (like Akka does with unidoc), how would the root documentation be merged?) This doesn't seem to be a new thing, so maybe it's not so important.

[jrudolph]

Another thing :)

Chromium shows this warning in the console:

'SVGElement.offsetWidth' is deprecated and will be removed in M50, around April 2016. See https://www.chromestatus.com/features/5724912467574784 for more details.

originating from the included jquery.js. It would probably make sense to proactively upgrade to a newer version of jquery to prevent future breakage.

[felixmulder]

Hej Johannes! Thanks for the update. I'll see if I can fix your text-overlap issue in the https://github.com/scala/scala/pull/4997 PR. Regarding the SVG-issues, I think that's an issue that's prevalent to the jQuery 1.9.x series (which supports the microsoft legacy browsers). I'll see how much of a pain it is to migrate, if it isn't too bad I'll put it in the same PR.

Regarding setting the root package. The "root" will be a theoretical package above the top packages. One dumb thing you might do is this: let's say you have akka._._ packages only, you'll see that in the akka directory there's an index.html just make that the root file served on the akka pages. EEEIK You'll get broken links to the root package which will be listed in the packages on the right.

I think @VladUreche would have more insight into this, but one thing I've been toying with is getting rid of the root package and having an optional Library page instead.

[VladUreche]

Well, if you want to land on a specific package just make the API link point to <scaladoc root>/subpackage/you/want/to/land/in. And the first page people will see is the one for subpackage.you.want.to.land.in.

[jrudolph]

@VladUreche yes, I guess that makes sense.

[janekdb]

I've been seeing some unexpected behaviour when using the X to clear the member filter, It fails to clear the text.

Demo: https://youtu.be/RLG0Rb6UNMs

Firefox: 41.0
Ubuntu 14.04.3 LTS

[janekdb]

Here's an idea.

Take a look at an example of grouped methods: https://github.com/scala/scala/pull/5034. It could be useful to have a fold/unfold arrow on the group name.

One problem with this would be a requirement to auto-expand a folded section if a user clicked a link to hidden member when that link is on the current page. There's a similar problem when the member filter has hidden members. Clicking a link to a hidden member fails to show the member.

[janekdb]

In 2.11.x the target member of a link did a Web 2.0 style fade from yellow to show it was the target.

This shows a case when that would have been useful: https://youtu.be/MUp5NpZDHOw

Because the target method withPositioning(pos) is close to the end of the page it cannot be scrolled to the top of the page leaving the user with no cue as the intended target.

[felixmulder]

@janekdb, first up - great work on https://github.com/scala/scala/pull/5034, it's gonna look waaay better than the current Predef page :+1:

I've been seeing some unexpected behaviour when using the X to clear the member filter, It fails to clear the text.

I figured out why this is. When the input-field loses focus, we hide the "x" - but, after a timeout, allowing a quick click. As such, if you're on a really fast computer (i.e. desktop) the timeout will actually beat your click. If you're on slow hardware and do a loooooong click - the same will happen. So how should we fix this? My suggestion is to always keep the "x" if there's text in the input-field - and on clear, remove it.

EDIT: https://github.com/scala/scala/pull/5039

One problem with this would be a requirement to auto-expand a folded section if a user clicked a link to hidden member when that link is on the current page. There's a similar problem when the member filter has hidden members. Clicking a link to a hidden member fails to show the member.

Good find, adding it to the list!

In 2.11.x the target member of a link did a Web 2.0 style fade from yellow to show it was the target.

Regression, this should still be there... :cry:

[adelbertc]

Given the prevalent use of type classes in the stdlib, cats, scalaz, shapeless, spire, algebra, etc. it would be super nice to have some kind of support for them in the Scaladoc. Some discussion on Gitter here: https://gitter.im/scala/scala?at=56f8dc3e76b6f9de194bbe35

[marconilanna]

scala.Predef is missing from sidebar when browsing other scala.X entities (might be all objects without companion class/trait)

It _is_ all objects without companion class/trait. A few other examples I could gather:

• object Platform in http://www.scala-lang.org/files/archive/nightly/2.12.x/api/2.12.x/scala/compat/index.html
• objects ForkJoinPool, ForkJoinTask, and ThreadLocalRandom in http://www.scala-lang.org/files/archive/nightly/2.12.x/api/2.12.x/scala/concurrent/forkjoin/index.html
• object StdIn in http://www.scala-lang.org/files/archive/nightly/2.12.x/api/2.12.x/scala/io/index.html

[marconilanna]

When browsing, the object, class, and trait icons are proper lined up: objects always on the first column, classes and traits always on the second (first image at http://imgur.com/a/c1uyX). When searching, however, things are all over the place (second and third images). It would be nice to have the same icons always on the same columns.

I don't know how an object without a companion class/trait would currently look like (see my previous comment above), but it should display on the first column, together with the other object icons.

[marconilanna]

These icons are very similar, it is difficult to tell them apart. More contrast/differentiation would be welcome:

• http://www.scala-lang.org/files/archive/nightly/2.12.x/api/2.12.x/lib/class.svg and http://www.scala-lang.org/files/archive/nightly/2.12.x/api/2.12.x/lib/class_comp.svg
• http://www.scala-lang.org/files/archive/nightly/2.12.x/api/2.12.x/lib/trait.svg and http://www.scala-lang.org/files/archive/nightly/2.12.x/api/2.12.x/lib/trait_comp.svg
• http://www.scala-lang.org/files/archive/nightly/2.12.x/api/2.12.x/lib/object.svg and http://www.scala-lang.org/files/archive/nightly/2.12.x/api/2.12.x/lib/object_comp.svg

[marconilanna]

We have http://www.scala-lang.org/files/archive/nightly/2.12.x/api/2.12.x/lib/object.svg and http://www.scala-lang.org/files/archive/nightly/2.12.x/api/2.12.x/lib/object_comp.svg icons. However, "object_comp.svg" is conceptually wrong. We need separate "object_class_comp.svg" and "object_trait_comp.svg" icons. Take, for instance, http://www.scala-lang.org/files/archive/nightly/2.12.x/api/2.12.x/scala/collection/mutable/ArrayOps$.html: the icon suggests this object has a companion class (green background), when in reality it has a companion trait (light blue background).

[felixmulder]

Thanks for the feedback @marconilanna. I've added the spacer issue to the TODO and differentiation of object_class_comp.svg and object_trait_comp.svg (see initial issue).

Regarding contrast and differentiation - I disagree. They're easy to tell apart and they have colors that follow the style of scala-lang, which is one of the goals of the redesign. We want the interface to be non-obtrusive and easy to look at for longer periods of time (which was one of the problems with the previous scaladoc). That being said - if you think you have a better idea for what the icons should look like, you're more than welcome to contribute a couple of svgs :)

[Sciss]

Looks great!

I'm having one issue on the desktop (Firefox 38 / Debian): When I try to expand the 'Full Signature' of a method that is shown as '[use case]', for example Option . max., the method body collapses. When I expand it again, the full signature is included. I suppose it should now collapse upon click on 'Full Signature'.

[felixmulder]

Thanks @sciss! Added it to the TODO - will have a look during the week/next week :)

[SethTisue]

@felixmulder are you aware of https://issues.scala-lang.org/browse/SI-9721 and https://issues.scala-lang.org/browse/SI-9722 ? I'd assign them to you in Jira, but you don't seem to have an account.

[felixmulder]

@SethTisue I'm aware of them and currently working on the latter in one branch. There's still one issue right now where final case classes don't make it to the searchable index - debugging...

I have an account, I've commented on the issues so you can assign them :)

[megri]

First of all, loving the new look&feel!

One of the coolest features is the smart search bar. However, the version active at http://www.scala-lang.org/files/archive/nightly/2.12.x/ doesn't allow us to search for members of "some" objects.

For an example, long2Long shows up as a member of Predef while int2long doesn't show up at all despite being a member of scala.Int

[felixmulder]

@megri: https://github.com/scala/scala/pull/5069 :)

[ianmackenzie]

One thing I would love (and maybe there's a way to do this that I'm missing) would be a way to add standalone pages to the generated documentation. I'm thinking of things like tutorials and examples that benefit from being integrated with the rest of the documentation (have the same style, be linked to from the relevant package/classes, link back to relevant classes etc.) but aren't specific to one particular class/object/package (or would be too big to include directly on the relevant page).

[felixmulder]

re @ianmackenzie:

One of the goals with the new documentation structure is to push users toward package level documentation. When visiting: http://www.scala-lang.org/files/archive/nightly/2.12.x/api/2.12.x/, you're greeted with the rootdoc.txt documentation specified by the -doc-root-content flag. In my case, with the new docs, I actually read this page for the first time. This gives me an overview of the different packages and what they're supposed to contain. Each package object that has a docstring do the same thing but for packages.

So in terms of pages that can contain examples and are somewhat decoupled from the code examples these two options are currently it. So no you're not missing anything.

My point is this - I think it'd be a nice contribution to look at how to parse rootdoc.txt and then create a structure where one can generate tutorials/misc pages using the same syntax as in docstrings.

Let's say you can specify a misc pages directory and then it's directory structure'll be copied into the generated page structure

└── infopages
    └── tutorials
        ├── collections
        │   └── forComprehensions.txt
        ├── futures.txt
        └── threadpools.txt

Would generate:

├── index.html
├── scala
│    └── collections
└── infopages
    └── tutorials
        ├── collections
        │   └── forComprehensions.html
        ├── futures.html
        └── threadpools.html

Is this something you'd be willing to implement @ianmackenzie ?

[tpolecat]

@ianmackenzie @felixmulder it would be great if standalone doc could have checked/interpreted code blocks as some of us now do with tut. This style of doc is increasingly popular at least in the FP-leaning Scala community.

[felixmulder]

@tpolecat: I completely agree. Could tut be modded to check {{{5+5}}} clauses?

[tpolecat]

@felixmulder sure ... see also sbt-doctest

[ianmackenzie]

@felixmulder I can hardly refuse a reasonable request like that! Should I open a new issue on https://issues.scala-lang.org? I'll take a read through the main Scala contribution guidelines/hacker guide; any other specific tips on where to start or are there any Scaladoc-specific coding conventions I should know about?

@tpolecat @felixmulder I also think it would be great to incorporate code evaluation into standalone pages, but that sounds a bit more intimidating (and sbt-doctest looks like a pretty good fallback). I'm wondering if it would be easier to provide some sort of a hook to allow plugins like tut to process documentation sources before conversion to HTML, instead of trying to build the functionality right into Scaladoc itself, but that seems like a separate issue.

[felixmulder]

@ianmackenzie: Read the scaladocs post on scala-lang.org, this should give you a head start :) Start with just getting a hello world parsing and then worry about tut/sbt-doctest later. Ping me on gitter if you need help!

Regarding the issue - not sure. Cc: @SethTisue

[lrytz]

@ianmackenzie @felixmulder if we go in that direction we should talk about how far we want to push it and where it ends. for example, how it relates to doc pages like docs.scala-lang.org (for scala, for example the collections overview) or project doc pages like typelevel.org/cats or lihaoyi.com/fastparse and the tools that generate it.

i personally think that scaladoc's structure is too rigid for most people to use it instead of some other doc tool. how hard would it be to implement that feature? would it complicate scaladoc for the user, clutter up the interface?

cc @heathermiller

[ianmackenzie]

@lrytz My hope was to be able to do something like what the Qt documentation does - it has lots of tutorial/example pages like http://doc.qt.io/qt-5/qtgui-openglwindow-example.html and http://doc.qt.io/qt-5/modelview.html that are nicely integrated with the API reference. I've always liked this model - if you're reading a tutorial you can easily jump to a class page for more details, and conversely if you're looking at the documentation for a class you can jump to a tutorial that shows how it can actually be used.

In Doxygen you can create standalone pages with the 'page' command (http://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmdpage). I was imagining something similar for Scaladoc - no new markup options, just some way of splitting some documentation out onto a separate page. But yes, if people started putting longer-form stuff in Scaladoc then I guess it's more likely that they might also want better support for images/tables/tables of contents/footnotes, which could get complex...

I guess the alternative is to have separate API reference and user guide/examples/tutorials like is done now, and just carefully link back and forth between them - not the end of the world, but a bit harder to maintain consistency, avoid broken links etc.

[felixmulder]

@lrytz @ianmackenzie: I agree with the sentiment - and IMO this should be limited to bring able to create a page like rootdoc.txt and linking to it.

[SethTisue]

Should I open a new issue on https://issues.scala-lang.org?

@ianmackenzie yes, I think it would be a good to have an enhancement-request ticket on this (automated checking of code examples in the doc). whether the Scala build could take on a tut dependency in order to get it is another question —let's discuss on the ticket

[janekdb]

This list would be better with an ordering that understands numbers,

Product
Product1
Product2
...
Product20
Product21
Product22

If we restricted the scope to names matching ^[^0-9]*[0-9]*$ we would cover ProductN, FunctionN and TupleN.

[VladUreche]

@janekdb @felixmulder in fact, Scaladoc had a hardcoded check to remove ProductN, TupleN and FunctionN for all N > 3. It may be that the latest batch of changes removed that check...

[janekdb]

@VladUreche @felixmulder. Alternative idea. Instead of restoring this restriction to N <= 3 stop special casing standard library class names and add a general purpose mechanism with associated command line configuration to achieve the same outcome.

And there's always an option to collapse N > 3 items from an identified sequence into some expandable UI element.

[VladUreche]

Good point @janekdb, thanks! Maybe an annotation like @notDocumentable or @notTemplate.

[VladUreche]

In fact, that's exactly the opposite of @template (and its alias @documentable), which says "although this entity is not documentable, please document it for me". As an alternative, we could use @template none instead of inventing a new annotation.

@janekdb, you really need to write that scaladoc tutorial! We have so many ways to tweak and inherit the comments (@inheritDoc, macros), tweak the implicits, tweak the diagrams, tweak the groups... it's really a pity that only a handful of people know all these things...

[janekdb]

@VladUreche - tutorial - yes - will make a start this week even if it's a baby step.

[VladUreche]

:+1: :100: if you need any help, ping me or @felixmulder!

[som-snytt]

Just thought I'd mention type hierarchy diagrams.

https://github.com/scala/scala-dev/issues/105

One wish list idea is ability to navigate down the hierarchy: at Seq, I see $colon$colon is a subclass. What makes it a subclass, I wonder? It would be fab if mousing over the subclass link also highlighted the diagram edges in which the subclass participates, so be clicking those boxes I can reach the subclass.

I'm not even a huge fan of such diagrams in general, but this seems like a useful to way to explore type forests.

[fdietze]

Hello everyone,

Things I noticed about the new docs:

• The input field "filter all members" shows an arrow on hover on the left and shifts the input field to the right. This a bit annoying. Idea: display the arrow on the right (maybe without hover).
• all ToggleContainers (example: Linear Supertypes) collapse when clicking the links or instantiating text selection. Idea: Only collapse when clicking on header.

I really like the new appearance! :+1:

[Ichoran]

The search is wonderful and the aesthetics are great!

But there are some niggling issues also, where the old format is quite superior IMO, and some other places where usability could be significantly enhanced with maybe not too much work.

1. Tree view on the right. Not only is it less common to have a right-leaning menu than left-, it's the opposite convention for no obvious reason. Why make people re-learn where to look? Maybe it looks enough better this way to be worth it--I haven't played with it--but it's worth thinking about seriously.
2. Very long class/method names can make the tree view dominate the window. It should be terminated at some shorter level (e.g. 20 chars) with ... (the unicode one, not what I just typed) and in that case the tooltip should start with the full actual name. Note that in 2.11, you could choose how wide this was!
3. It is almost impossible to compare classes within different packages. Before you could at least scroll up and down to notice the similarity between scala.collection.immutable and scala.collection.mutable. Now you're really stuck. A "pin open" feature for the tree view would help solve this.
4. The color for packages is too close to the color for traits and objects. Use some other part of color space--make it much lighter with dark text, or add a lot of purple, or something. It used to be more purple.
5. The flippy rolodex look to the C or O in the big icon on the main view does not make it at all obvious that you can click on it to switch them. Some sort of C <--> O view would be a lot more obvious (with the one you don't have being faded out).
6. Despite being gorgeous, the screen space is not used very efficiently. For those with less than vast monitors, this can be a sizable drawback.
   
   
   
   1. The tree menu items are practically double-spaced. They should be closer.
   
   
   2. The main icon and package/class/object name are too big. Big is elegant. This is more than is needed.
   
   
   3. Linear Supertypes and Known Subclasses take a lot of space as headings, and are kind of the same thing. You could merge both into a single heading "Inheritance Hierarchy". (It's still way better than the old mess of putting everything in at full size.)
   
   
   4. The filter bar's dark border is about 50% wider than it needs to be to look pretty.
   
   
   5. The type signatures reserve a huge border of space on the left for protected abstract class or somesuch. Leaving enough room for "final class" and "abstract def" is good. More than that should wrap. Yes, you lose some vertical space when you wrap, but the gain in horizontal space is worth it.
   
   
   6. In inheritance ordering, there is a surprising amount of space between "inherited from blah" and e.g. "Value Members". (This is also one of the very few cases where it looked way better in 2.11; this is really washed out and spaced apart.)
   
   
7. The Linear Supertypes are always a pain to read, but the layout here is especially a pain. Splitting each supertype onto its own line would make it a lot easier to follow (or maybe putting each one into a little wrappable box--the commas just don't cut it when there are 25 of them with multiple type parameters in each).
8. There is no indication that a method description contains more stuff. There is always more stuff when you click, but showing a little [+] or something on hover would help. Whether you always do it or only do it when there is more stuff to display (i.e. not just the definitions classes stuff) I don't have an opinion on.
9. The "Type Hierarchy" is displayed inconsistently. When it appears (e.g. with scala.runtime.FractionalProxy) it duplicates the information in supertypes and subclasses. It's fine to have, but when it's available I think it should be tucked into a single tab (maybe as an alternate view to the supertypes/subclasses listing).
10. Filter All Members should always display the arrow to expand it into the full view. Otherwise it's hard to realize that there's even anything there to find. (I only found it because I was looking for it after having used 2.11's view.)
11. If you have a narrow window your signatures may be incomplete! If you look, for instance, at scala.Option in a narrow window, you cannot tell that collect is a final def. The final just disappears, expanded or not. It's not wrapped or clipped or anything--just gone.

[felixmulder]

Great analysis! Could you open issues on these and tag them beginner friendly?

We have a blog post somewhere helping people into this part of the compiler.

These points are excellent as beginner tasks IMO, especially if you know your way around HTML/CSS/JS :)

[nrinaudo]

I don't know whether this is still active, or an appropriate place to post this. If not, my apologies.

A recurring annoyance with scaladoc comment inheritance is that it doesn't work cross dependencies, even if the dependency's sources are available in standard maven artifacts, in standard maven repositories.

Some of my librarie are basically specific wrappers and type aliases for a more generic one - I have a generic codec lib, for example, with specific cxv, xml, ... implementations. The current behaviour means that my csv library, for instance, has almost no scaladoc, except for the bits that are specific or explicitly overidden.

[pgrandjean]

Hi, I would like to report a new issue on scaladoc. Maybe it's already known. I have a project with only one package object containing a number of functions. No classes, no other objects, only a package object foo. In this case, scaladoc generates documentation with nothing else except a root package. The functions are not documented either.

[SethTisue]

@pgrandjean sounds like https://github.com/scala/bug/issues/8124

[dwijnand]

Closing as this is a big ticket, with lots of finished work in it. If any of the remaining points are especially significant, let's fork it off into a separate issue.