Issues and Ideas for Scaladoc #84

Open
felixmulder opened this Issue Feb 10, 2016 · 53 comments

Comments

Projects
None yet
@felixmulder

felixmulder commented Feb 10, 2016

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: scala/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: scala/scala#5077)
  • scala.Predef is missing from sidebar when browsing other scala.X entities (might be all objects without companion class/trait) (fixed in: scala/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: scala/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: scala/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 (scala/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: scala/scala#4912 (comment)
  • Keyboard navigation for members
  • Member indentation: scala/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] scala/scala#4912 (comment)
  • Enable member filtering for types scala/scala#4972

Mobile Issues

General

  • When rotating the phone to landscape the font becomes quite large (compare [1] and [2]) see scala/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 scala/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)

@felixmulder felixmulder changed the title from Issues for Scaladoc to Issues and Ideas for Scaladoc Feb 16, 2016

@jrudolph

This comment has been minimized.

Show comment
Hide comment
@jrudolph

jrudolph Feb 18, 2016

Member

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

jrudolph commented Feb 18, 2016

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

This comment has been minimized.

Show comment
Hide comment
@felixmulder

felixmulder Feb 18, 2016

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

This comment has been minimized.

Show comment
Hide comment
@jrudolph

jrudolph Feb 23, 2016

Member

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

Member

jrudolph commented Feb 23, 2016

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

This comment has been minimized.

Show comment
Hide comment
@jrudolph

jrudolph Feb 23, 2016

Member

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.

Member

jrudolph commented Feb 23, 2016

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

This comment has been minimized.

Show comment
Hide comment
@felixmulder

felixmulder Feb 23, 2016

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

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

This comment has been minimized.

Show comment
Hide comment
@felixmulder

felixmulder Feb 24, 2016

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

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

This comment has been minimized.

Show comment
Hide comment
@jrudolph

jrudolph Feb 24, 2016

Member

I snuck a fix for this:

Cool :)

No urgency from my side to fix those things.

Member

jrudolph commented Feb 24, 2016

I snuck a fix for this:

Cool :)

No urgency from my side to fix those things.

@jrudolph

This comment has been minimized.

Show comment
Hide comment
@jrudolph

jrudolph Feb 29, 2016

Member

Two things in the latest merged version:

  • some text overlap:

screenshot from 2016-02-29 14 19 44

  • 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.
Member

jrudolph commented Feb 29, 2016

Two things in the latest merged version:

  • some text overlap:

screenshot from 2016-02-29 14 19 44

  • 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

This comment has been minimized.

Show comment
Hide comment
@jrudolph

jrudolph Feb 29, 2016

Member

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.

Member

jrudolph commented Feb 29, 2016

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

This comment has been minimized.

Show comment
Hide comment
@felixmulder

felixmulder Feb 29, 2016

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.

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

This comment has been minimized.

Show comment
Hide comment
@VladUreche

VladUreche Mar 1, 2016

Member

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.

Member

VladUreche commented Mar 1, 2016

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

This comment has been minimized.

Show comment
Hide comment
@jrudolph

jrudolph Mar 1, 2016

Member

@VladUreche yes, I guess that makes sense.

Member

jrudolph commented Mar 1, 2016

@VladUreche yes, I guess that makes sense.

@janekdb

This comment has been minimized.

Show comment
Hide comment
@janekdb

janekdb Mar 13, 2016

Member

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

Member

janekdb commented Mar 13, 2016

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

This comment has been minimized.

Show comment
Hide comment
@janekdb

janekdb Mar 13, 2016

Member

Here's an idea.

Take a look at an example of grouped methods: scala/scala#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.

Member

janekdb commented Mar 13, 2016

Here's an idea.

Take a look at an example of grouped methods: scala/scala#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

This comment has been minimized.

Show comment
Hide comment
@janekdb

janekdb Mar 13, 2016

Member

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.

Member

janekdb commented Mar 13, 2016

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

This comment has been minimized.

Show comment
Hide comment
@felixmulder

felixmulder Mar 14, 2016

@janekdb, first up - great work on scala/scala#5034, it's gonna look waaay better than the current Predef page 👍

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

@janekdb, first up - great work on scala/scala#5034, it's gonna look waaay better than the current Predef page 👍

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

@adelbertc

This comment has been minimized.

Show comment
Hide comment
@adelbertc

adelbertc Mar 28, 2016

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

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

This comment has been minimized.

Show comment
Hide comment
@marconilanna

marconilanna Mar 28, 2016

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:

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

This comment has been minimized.

Show comment
Hide comment
@marconilanna

marconilanna Mar 28, 2016

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.

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

This comment has been minimized.

Show comment
Hide comment
@marconilanna

marconilanna Mar 28, 2016

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

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

This comment has been minimized.

Show comment
Hide comment
@felixmulder

felixmulder Mar 28, 2016

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

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

This comment has been minimized.

Show comment
Hide comment
@Sciss

Sciss Mar 29, 2016

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

Sciss commented Mar 29, 2016

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

This comment has been minimized.

Show comment
Hide comment
@felixmulder

felixmulder Mar 29, 2016

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

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

@SethTisue

This comment has been minimized.

Show comment
Hide comment
@SethTisue

SethTisue Mar 29, 2016

Member

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

Member

SethTisue commented Mar 29, 2016

@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

This comment has been minimized.

Show comment
Hide comment
@felixmulder

felixmulder Mar 30, 2016

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

@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

This comment has been minimized.

Show comment
Hide comment
@megri

megri Mar 30, 2016

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

megri commented Mar 30, 2016

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

This comment has been minimized.

Show comment
Hide comment

@megri: scala/scala#5069 :)

@ianmackenzie

This comment has been minimized.

Show comment
Hide comment
@ianmackenzie

ianmackenzie Mar 31, 2016

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

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

This comment has been minimized.

Show comment
Hide comment
@felixmulder

felixmulder Mar 31, 2016

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 ?

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

This comment has been minimized.

Show comment
Hide comment
@tpolecat

tpolecat Mar 31, 2016

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

@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

This comment has been minimized.

Show comment
Hide comment
@felixmulder

felixmulder Mar 31, 2016

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

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

@tpolecat

This comment has been minimized.

Show comment
Hide comment
@tpolecat

tpolecat Mar 31, 2016

@felixmulder sure ... see also sbt-doctest

@felixmulder sure ... see also sbt-doctest

@ianmackenzie

This comment has been minimized.

Show comment
Hide comment
@ianmackenzie

ianmackenzie Apr 1, 2016

@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 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

This comment has been minimized.

Show comment
Hide comment
@felixmulder

felixmulder Apr 1, 2016

@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

@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

This comment has been minimized.

Show comment
Hide comment
@lrytz

lrytz Apr 1, 2016

Member

@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

Member

lrytz commented Apr 1, 2016

@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

This comment has been minimized.

Show comment
Hide comment
@ianmackenzie

ianmackenzie Apr 1, 2016

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

@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

This comment has been minimized.

Show comment
Hide comment
@felixmulder

felixmulder Apr 1, 2016

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

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

@felixmulder felixmulder referenced this issue in scala/scala Apr 3, 2016

Merged

Minor fixes to Scaladoc #5077

@SethTisue

This comment has been minimized.

Show comment
Hide comment
@SethTisue

SethTisue Apr 4, 2016

Member

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

Member

SethTisue commented Apr 4, 2016

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

@retronym retronym added the c:scaladoc label Apr 14, 2016

@janekdb

This comment has been minimized.

Show comment
Hide comment
@janekdb

janekdb Apr 19, 2016

Member

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.

Member

janekdb commented Apr 19, 2016

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

This comment has been minimized.

Show comment
Hide comment
@VladUreche

VladUreche Apr 19, 2016

Member

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

Member

VladUreche commented Apr 19, 2016

@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

This comment has been minimized.

Show comment
Hide comment
@janekdb

janekdb Apr 19, 2016

Member

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

Member

janekdb commented Apr 19, 2016

@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

This comment has been minimized.

Show comment
Hide comment
@VladUreche

VladUreche Apr 19, 2016

Member

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

Member

VladUreche commented Apr 19, 2016

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

@VladUreche

This comment has been minimized.

Show comment
Hide comment
@VladUreche

VladUreche Apr 19, 2016

Member

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

Member

VladUreche commented Apr 19, 2016

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

This comment has been minimized.

Show comment
Hide comment
@janekdb

janekdb Apr 19, 2016

Member

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

Member

janekdb commented Apr 19, 2016

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

@VladUreche

This comment has been minimized.

Show comment
Hide comment
@VladUreche

VladUreche Apr 19, 2016

Member

👍 💯 if you need any help, ping me or @felixmulder!

Member

VladUreche commented Apr 19, 2016

👍 💯 if you need any help, ping me or @felixmulder!

@som-snytt

This comment has been minimized.

Show comment
Hide comment
@som-snytt

som-snytt Jun 3, 2016

Just thought I'd mention type hierarchy diagrams.

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

Just thought I'd mention type hierarchy diagrams.

#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

This comment has been minimized.

Show comment
Hide comment
@fdietze

fdietze Jun 18, 2016

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! 👍

fdietze commented Jun 18, 2016

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! 👍

@Ichoran

This comment has been minimized.

Show comment
Hide comment
@Ichoran

Ichoran Nov 10, 2016

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.

Ichoran commented Nov 10, 2016

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

This comment has been minimized.

Show comment
Hide comment
@felixmulder

felixmulder Nov 10, 2016

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

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

This comment has been minimized.

Show comment
Hide comment
@nrinaudo

nrinaudo Jul 24, 2017

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.

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

This comment has been minimized.

Show comment
Hide comment
@pgrandjean

pgrandjean Nov 6, 2017

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.

image

pgrandjean commented Nov 6, 2017

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.

image

@SethTisue

This comment has been minimized.

Show comment
Hide comment
Member

SethTisue commented Nov 6, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment