Scala Programming Language
  1. Scala Programming Language
  2. SI-5784

Type synonyms should be listed on left hand side

    Details

    • Type: Improvement Improvement
    • Status: Open
    • Priority: Minor Minor
    • Resolution: Unresolved
    • Affects Version/s: None
    • Fix Version/s: None
    • Component/s: Scaladoc Tool
    • Labels:

      Description

      Type synonyms in package objects are only listed on the right-hand side of the scaladoc, if you first click on the package object on the left-hand side. They are never listed on the left-hand side. This has confused me, a relative Scala newbie, a number of times.

        Activity

        Hide
        Vlad Ureche added a comment -

        Thanks for reporting it, Robin.

        Heather, what do you think of this? Do you see any way of adding aliased types (type synonyms) without cluttering the right sidebar?

        Show
        Vlad Ureche added a comment - Thanks for reporting it, Robin. Heather, what do you think of this? Do you see any way of adding aliased types (type synonyms) without cluttering the right sidebar?
        Hide
        Heather Miller added a comment -

        Good observation. Though, I'm not so sure it makes a lot of sense to list type aliases in the left side-bar-- you can't click to navigate to a type alias. If there was a way to link to methods in Scaladoc, this would make a bit more sense. Then, you could at least link to the type member on the package page. But regardless, I think that adding type aliases to the left sidebar would likely add a lot of noise that people might not like in general.

        Show
        Heather Miller added a comment - Good observation. Though, I'm not so sure it makes a lot of sense to list type aliases in the left side-bar-- you can't click to navigate to a type alias. If there was a way to link to methods in Scaladoc, this would make a bit more sense. Then, you could at least link to the type member on the package page. But regardless, I think that adding type aliases to the left sidebar would likely add a lot of noise that people might not like in general.
        Hide
        Robin Green added a comment -

        OK, for the link, you could use a HTML anchor (<a name="type"/>). To allow people to remove the extra noise, you could have a toggle, much like "Display package names only", which could say something like "Hide type synonyms". Or you could convert the "Display package names only" toggle into a tristate button, but I don't like that because it would be less obvious.

        Show
        Robin Green added a comment - OK, for the link, you could use a HTML anchor (<a name="type"/>). To allow people to remove the extra noise, you could have a toggle, much like "Display package names only", which could say something like "Hide type synonyms". Or you could convert the "Display package names only" toggle into a tristate button, but I don't like that because it would be less obvious.
        Hide
        Vlad Ureche added a comment -

        Thinking more about it, I would rather improve the documentation for the root package than putting type aliases in the list: Program-wide type aliases are defined in the scala package and in scala.Predef, both of which are automatically imported. Since this solution would only work for half the problem (the scala package) I would suggest not putting in into practice, but rather thinking of a better alternative.

        Show
        Vlad Ureche added a comment - Thinking more about it, I would rather improve the documentation for the root package than putting type aliases in the list: Program-wide type aliases are defined in the scala package and in scala.Predef , both of which are automatically imported. Since this solution would only work for half the problem (the scala package) I would suggest not putting in into practice, but rather thinking of a better alternative.
        Hide
        Vlad Ureche added a comment -

        Bumping to Critical, this will be need to document reflection.

        Show
        Vlad Ureche added a comment - Bumping to Critical, this will be need to document reflection.
        Show
        Adriaan Moors added a comment - https://github.com/scala/scala/pull/925
        Hide
        Vlad Ureche added a comment -

        For alias and abstract types this it is now possible to annotate the doc comment with @documentable (or @template) to get a page for the type and list it on the right:

        /** ...
         *  @template
         */
        type Set[A]     = immutable.Set[A]
        

        I will leave this bug open so we decide if we really want to have that for java classes, for which we don't have any doc comments. (String is a good example, you'll get a page with all of String's methods, but none of them has comments, as the class is Java-defined and the source code is not recompiled)

        Show
        Vlad Ureche added a comment - For alias and abstract types this it is now possible to annotate the doc comment with @documentable (or @template ) to get a page for the type and list it on the right: /** ... * @template */ type Set[A] = immutable.Set[A] I will leave this bug open so we decide if we really want to have that for java classes, for which we don't have any doc comments. (String is a good example, you'll get a page with all of String's methods, but none of them has comments, as the class is Java-defined and the source code is not recompiled)
        Hide
        James Iry added a comment -

        2.10.2 is about to be cut. Kicking down the road and un-assigning to foster work stealing.

        Show
        James Iry added a comment - 2.10.2 is about to be cut. Kicking down the road and un-assigning to foster work stealing.

          People

          • Assignee:
            Unassigned
            Reporter:
            Robin Green
            TracCC:
            Heather Miller, Heather Miller
          • Votes:
            0 Vote for this issue
            Watchers:
            7 Start watching this issue

            Dates

            • Created:
              Updated:

              Development