search

scala / scala-dev

Scala 2 team issues. Not for user-facing bugs or directly actionable user-facing improvements. For build/test/infra and for longer-term planning and idea tracking. Our bug tracker is at https://github.com/scala/bug/issues
Apache License 2.0
130 stars 14 forks source link

Issues and Ideas for Scaladoc #84

Closed felixmulder closed 4 years ago

felixmulder commented 8 years ago

Ideas / General Issues

jrudolph commented 8 years ago

Here are a few more suggestions:

felixmulder commented 8 years ago

@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 commented 8 years ago

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 commented 8 years ago

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 commented 8 years ago

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 commented 8 years ago

@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 commented 8 years ago

I snuck a fix for this:

Cool :)

No urgency from my side to fix those things.

jrudolph commented 8 years ago

Two things in the latest merged version:

screenshot from 2016-02-29 14 19 44

jrudolph commented 8 years ago

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 commented 8 years ago

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 commented 8 years ago

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 commented 8 years ago

@VladUreche yes, I guess that makes sense.

janekdb commented 8 years ago

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 commented 8 years ago

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 commented 8 years ago

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 commented 8 years ago

@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 commented 8 years ago

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 commented 8 years ago

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:

marconilanna commented 8 years ago

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 commented 8 years ago

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

marconilanna commented 8 years ago

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 commented 8 years ago

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 commented 8 years ago

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 commented 8 years ago

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

SethTisue commented 8 years ago

@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 commented 8 years ago

@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 commented 8 years ago

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 commented 8 years ago

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

ianmackenzie commented 8 years ago

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 commented 8 years ago

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 commented 8 years ago

@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 commented 8 years ago

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

tpolecat commented 8 years ago

@felixmulder sure ... see also sbt-doctest

ianmackenzie commented 8 years ago

@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 commented 8 years ago

@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 commented 8 years ago

@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 commented 8 years ago

@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 commented 8 years ago

@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 commented 8 years ago

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 commented 8 years ago

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

Product Product1 Product2 ... Product20 Product21 Product22

scaladoc-ordering-with-numerical-understanding

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

VladUreche commented 8 years ago

@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 commented 8 years ago

@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 commented 8 years ago

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

VladUreche commented 8 years ago

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 commented 8 years ago

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

VladUreche commented 8 years ago

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

som-snytt commented 8 years ago

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 commented 8 years ago

Hello everyone,

Things I noticed about the new docs:

I really like the new appearance! :+1:

Ichoran commented 8 years ago

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 commented 8 years ago

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 :)