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.
• Differentiate between object_class_comp.svg and object_trait_comp.svg (fixed in: Minor fixes to Scaladoc scala#5077)
• 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: Minor fixes to Scaladoc scala#5077)
• scala.Predef is missing from sidebar when browsing other scala.X entities (might be all objects without companion class/trait) (fixed in: Minor fixes to Scaladoc scala#5077)
• Predef extends ... needs to go away (sidebar)
• 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: Minor fixes to Scaladoc scala#5077)
• Add type members to search in IndexScript.scala
• Be able to navigate back to search results from a clicked search result entity
• Fix regression where anchor-links don't highlight the target member
• Fix anchor links mentioned here: Remove mention of deprecated I/O methods from Predef main comment scala#5018 (comment)
• Change behavior of "x"-button on input fields to only be removed if there is no input (changed from .on("blur", function () { ... }))
• Remove Template.scala and other unused files
• Remove dark bg on entity #definition
• Remove unfold arrows in favor of highlighted left side
• Unclutter contained classes (i.e. classes listed in package definition)
• Hover-text on packages
• Add sub-packages to side along with parent package of current entity for quick nav
• Useful search result hover text use first sentence until the next point is added (Scaladoc: Add better hover-text in search results scala#4978)
• Add @shortDescription annotation for use with hover-text and short method summary
  StreamBuffer in Graphviz. Vlad says to instantiate a generator for each Graphviz
• 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: add new search - featuring entity and member search scala#4912 (comment)
• Keyboard navigation for members
• Member indentation: add new search - featuring entity and member search scala#4912 (comment)
  • 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)
• Clicking on a package doesn't open its doc
• There's a triangle when on top of the modifiers when looking at the "Full Signature" (TraversableLike.foreach), see [3] add new search - featuring entity and member search scala#4912 (comment)
• Enable member filtering for types Add package member filtering scala#4972

Mobile Issues

General

• When rotating the phone to landscape the font becomes quite large (compare [1] and [2]) see add new search - featuring entity and member search scala#4912 (comment)
• Unfolding the doc comment of TraversableOnce.reduceRight: the text is too large and overflow, not everything is readable
• Remove auto-capitalization in input field (by: @lrytz)
• There's no more get the abstract modifier (TraversableLike.foreach, package mutable) - is that by design?

Android

• On phones with large resolutions (1440x2560) method indentation is weird (should be fixed by add new search - featuring entity and member search scala#4912)
• 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.
• 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
• Jumpy scroll sometimes, sometimes only header moves (Safari & Chrome)
• Some pages take a really long time to display - could be because of dropbox hosting (Chrome & Safari)
• When clicking on a member, the page sometimes jumps to the top (Chrome & Safari)
• 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 👍 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 scala/scala#4983 👍

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 scala/scala#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.