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)

[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.