This page is no longer maintained — Please continue to the home page at www.scala-lang.org

Scaladoc 2

40 replies
dubochet
Joined: 2008-06-30,
User offline. Last seen 1 year 36 weeks ago.

As of revision 19844, Scaladoc 2 replace the old Scaladoc in all trunk and 2.8
builds. Have a look at the trunk nightly Scaladoc.

http://www.scala-lang.org/archives/downloads/distrib/files/nightly/docs/...

Scaladoc 2 is a major update to Scaladoc by Manohar Jonnalagedda and Gilles
Dubochet. It is based on the original Scaladoc (Sean McDirmid, Geoffrey
Washburn, Vincent Cremet and Stéphane Michleoud) as well as on vScaladoc (David
Bernard).

Beside usual bug reports, I am interested in feedback concerning the usability
of Scaladoc. Please, send in use-cases of what you were searching for, and why
you did or did not find it easily in Scaladoc. General feedback about the look
and feel of Scaladoc is also wanted.

A new look and feel for documentation pages
-------------------------------------------

The left bar of the documentation page, listing packages and top-level objects,
is simpler. There are no separate lists for packages, classes and objects.
Instead, there is a single list contains packages and their nested classes and
objects. Classes and their companion objects are a single entry in the list. A
text box at the top of the list (look for an empty blank space) allows to
interactively filter the list by entering a package name, class name, or a part
thereof.

The right side of the page, with the documentation for a single class, trait,
object or package, is organized differently. Most notably:
- All members, inherited or locally defined are listed as actual members (not
just links to the definition in the super-class), with their types as seen
from the current class.
- There is no more distinction between vals, defs, classes, types, etc.
Instead, members are subdivided into three categories:
- value members (defs, vals, vars, objects, packages) that result in a value
(and possibly a side-effect) when they are accessed;
- type members (traits, classes, abstract types, type aliases) that result
in a type (and possibly a constructor) when they are accessed;
- instance constructors for the class.
- At the top of the members list is a field titled "inherits" that contains
the linearization of the class's ancestors (see the Scala language
specification §5.1.2). This is a list of all classes from which the current
class can inherit members. Clicking on the ancestors selects which inherited
members are listed. If all ancestors are grayed out, only locally defined or
overridden members are listed.
- Each package has its own page.

Wiki-like syntax in documentation source
----------------------------------------

Authors of documentation no longer have to use HTML tags in their comments.
Instead, Scaladoc supports a wiki-like syntax very similar to that used in Trac.
In general, Scaladoc authors should no longer use HTML tags in documentation as
Scaladoc may in the future also generate documentation in other formats than
HTML.

Wiki syntax is dependent of left-side alignment: the star marking the beginning
of a Scaladoc line marks the beginning of the left side for parsing purposes
(start-of-line markers are mandatory). Here is a small example of Scaladoc-
supported wiki syntax.

/** This is a paragraph
*
* This is another paragraph (note the empty line above) containing '''bold''',
* ''italic'', `monospace`,
* __underline__, ^superscript^, and ,,subscript,, words.
*
* {{{
* Multi-line code can be inserted as a block and will be printed as monospace
* text.
* It isn't parsed as Scala, with keyword highlighting, but may be in the
* future.
* }}}
*
* In the near future, wiki syntax will also support bullet or number lists as
* well as links to the www and to other pages inside the documentation. */

Compile-time error checking of documentation source
---------------------------------------------------

The Scaladoc comment parser will report invalid tags. Valid tags are:
- @author (multiple allowed);
- @see (multiple allowed);
- @return (one allowed);
- @throws (one allowed per exception);
- @param (one allowed per value parameter);
- @tparam (one allowed per type parameter);
- @version (one allowed);
- @since (one allowed);
- @todo (multiple allowed);
- @deprecated (multiple allowed).

The Scaladoc comment parser will report invalid wiki syntax, such as unclosed
formatting ('''bold for example), unclosed code blocks, or missing start-of-line
markers.

Missing features
----------------

Scaladoc 2 is still in development. This is a list of missing features.

- Documentation:
- Inheritance chain of members (definition class, then all overrides) is
printed.
- Subclasses are printed.
- Templates (classes, traits and objects) in types are links.
- Each owner element (at the top of the page) is a link.
- Documentation source at top of package objects is used by Scaladoc.
- Function, Tuple and Product classes are not listed.
- More comment tags are printed in the documentation (author, see, since,
etc.).
- There is a link to the source.

- Wiki syntax:
- Supports link tags.
- Supports bullet or number lists.

- HTML:
- Pages works as expected in Internet Explorer 8 & 9 (possibly also 7,
certainly not 6).
- The right side of the page is more compact, with less padding and smaller
text.
- The filter tool for packages is easily recognizable for what it is, not
just an empty, mysterious space.
- There is a filter tool for members.
- The filter tool has a better performance for large documentation.
- Documentation for members is hidden by default and shown when clicking the
signature.
- Documentation for value and type parameters is shown when clicking the
parameter name.

Tony Morris 2
Joined: 2009-03-20,
User offline. Last seen 42 years 45 weeks ago.
Re: Scaladoc 2

Hi Giles,
Is it easy to implement the ability to link between the object/trait
from within the document itself rather than the left pane?

e.g. A link to object Option from
http://www.scala-lang.org/archives/downloads/distrib/files/nightly/docs/...

Also, for sealed traits, it is possible to link to the subclasses? e.g.
a link to Some/None from Option?

Gilles Dubochet wrote:
> As of revision 19844, Scaladoc 2 replace the old Scaladoc in all trunk and 2.8
> builds. Have a look at the trunk nightly Scaladoc.
>
> http://www.scala-lang.org/archives/downloads/distrib/files/nightly/docs/...
>
> Scaladoc 2 is a major update to Scaladoc by Manohar Jonnalagedda and Gilles
> Dubochet. It is based on the original Scaladoc (Sean McDirmid, Geoffrey
> Washburn, Vincent Cremet and Stéphane Michleoud) as well as on vScaladoc (David
> Bernard).
>
> Beside usual bug reports, I am interested in feedback concerning the usability
> of Scaladoc. Please, send in use-cases of what you were searching for, and why
> you did or did not find it easily in Scaladoc. General feedback about the look
> and feel of Scaladoc is also wanted.
>
> A new look and feel for documentation pages
> -------------------------------------------
>
> The left bar of the documentation page, listing packages and top-level objects,
> is simpler. There are no separate lists for packages, classes and objects.
> Instead, there is a single list contains packages and their nested classes and
> objects. Classes and their companion objects are a single entry in the list. A
> text box at the top of the list (look for an empty blank space) allows to
> interactively filter the list by entering a package name, class name, or a part
> thereof.
>
> The right side of the page, with the documentation for a single class, trait,
> object or package, is organized differently. Most notably:
> - All members, inherited or locally defined are listed as actual members (not
> just links to the definition in the super-class), with their types as seen
> from the current class.
> - There is no more distinction between vals, defs, classes, types, etc.
> Instead, members are subdivided into three categories:
> - value members (defs, vals, vars, objects, packages) that result in a value
> (and possibly a side-effect) when they are accessed;
> - type members (traits, classes, abstract types, type aliases) that result
> in a type (and possibly a constructor) when they are accessed;
> - instance constructors for the class.
> - At the top of the members list is a field titled "inherits" that contains
> the linearization of the class's ancestors (see the Scala language
> specification §5.1.2). This is a list of all classes from which the current
> class can inherit members. Clicking on the ancestors selects which inherited
> members are listed. If all ancestors are grayed out, only locally defined or
> overridden members are listed.
> - Each package has its own page.
>
> Wiki-like syntax in documentation source
> ----------------------------------------
>
> Authors of documentation no longer have to use HTML tags in their comments.
> Instead, Scaladoc supports a wiki-like syntax very similar to that used in Trac.
> In general, Scaladoc authors should no longer use HTML tags in documentation as
> Scaladoc may in the future also generate documentation in other formats than
> HTML.
>
> Wiki syntax is dependent of left-side alignment: the star marking the beginning
> of a Scaladoc line marks the beginning of the left side for parsing purposes
> (start-of-line markers are mandatory). Here is a small example of Scaladoc-
> supported wiki syntax.
>
> /** This is a paragraph
> *
> * This is another paragraph (note the empty line above) containing '''bold''',
> * ''italic'', `monospace`,
> * __underline__, ^superscript^, and ,,subscript,, words.
> *
> * {{{
> * Multi-line code can be inserted as a block and will be printed as monospace
> * text.
> * It isn't parsed as Scala, with keyword highlighting, but may be in the
> * future.
> * }}}
> *
> * In the near future, wiki syntax will also support bullet or number lists as
> * well as links to the www and to other pages inside the documentation. */
>
> Compile-time error checking of documentation source
> ---------------------------------------------------
>
> The Scaladoc comment parser will report invalid tags. Valid tags are:
> - @author (multiple allowed);
> - @see (multiple allowed);
> - @return (one allowed);
> - @throws (one allowed per exception);
> - @param (one allowed per value parameter);
> - @tparam (one allowed per type parameter);
> - @version (one allowed);
> - @since (one allowed);
> - @todo (multiple allowed);
> - @deprecated (multiple allowed).
>
> The Scaladoc comment parser will report invalid wiki syntax, such as unclosed
> formatting ('''bold for example), unclosed code blocks, or missing start-of-line
> markers.
>
> Missing features
> ----------------
>
> Scaladoc 2 is still in development. This is a list of missing features.
>
> - Documentation:
> - Inheritance chain of members (definition class, then all overrides) is
> printed.
> - Subclasses are printed.
> - Templates (classes, traits and objects) in types are links.
> - Each owner element (at the top of the page) is a link.
> - Documentation source at top of package objects is used by Scaladoc.
> - Function, Tuple and Product classes are not listed.
> - More comment tags are printed in the documentation (author, see, since,
> etc.).
> - There is a link to the source.
>
> - Wiki syntax:
> - Supports link tags.
> - Supports bullet or number lists.
>
> - HTML:
> - Pages works as expected in Internet Explorer 8 & 9 (possibly also 7,
> certainly not 6).
> - The right side of the page is more compact, with less padding and smaller
> text.
> - The filter tool for packages is easily recognizable for what it is, not
> just an empty, mysterious space.
> - There is a filter tool for members.
> - The filter tool has a better performance for large documentation.
> - Documentation for members is hidden by default and shown when clicking the
> signature.
> - Documentation for value and type parameters is shown when clicking the
> parameter name.
>
>

loverdos
Joined: 2008-11-18,
User offline. Last seen 2 years 27 weeks ago.
Re: Scaladoc 2

Hi Gilles,

On Wed, Nov 25, 2009 at 11:26, Gilles Dubochet wrote:
> As of revision 19844, Scaladoc 2 replace the old Scaladoc in all trunk and 2.8
> builds. Have a look at the trunk nightly Scaladoc.
>
> http://www.scala-lang.org/archives/downloads/distrib/files/nightly/docs/...
>
> Scaladoc 2 is a major update to Scaladoc by Manohar Jonnalagedda and Gilles
> Dubochet. It is based on the original Scaladoc (Sean McDirmid, Geoffrey
> Washburn, Vincent Cremet and Stéphane Michleoud) as well as on vScaladoc (David
> Bernard).
>
> Beside usual bug reports, I am interested in feedback concerning the usability
> of Scaladoc. Please, send in use-cases of what you were searching for, and why
> you did or did not find it easily in Scaladoc. General feedback about the look
> and feel of Scaladoc is also wanted.
>
> A new look and feel for documentation pages
> -------------------------------------------
>
> The left bar of the documentation page, listing packages and top-level objects,
> is simpler. There are no separate lists for packages, classes and objects.
> Instead, there is a single list contains packages and their nested classes and
> objects. Classes and their companion objects are a single entry in the list. A
> text box at the top of the list (look for an empty blank space) allows to
> interactively filter the list by entering a package name, class name, or a part
> thereof.
>
> The right side of the page, with the documentation for a single class, trait,
> object or package, is organized differently. Most notably:
>  - All members, inherited or locally defined are listed as actual members (not
>    just links to the definition in the super-class), with their types as seen
>    from the current class.
>  - There is no more distinction between vals, defs, classes, types, etc.
>    Instead, members are subdivided into three categories:
>    - value members (defs, vals, vars, objects, packages) that result in a value
>      (and possibly a side-effect) when they are accessed;
>    - type members (traits, classes, abstract types, type aliases) that result
>      in a type (and possibly a constructor) when they are accessed;
>    - instance constructors for the class.
>  - At the top of the members list is a field titled "inherits" that contains
>    the linearization of the class's ancestors (see the Scala language
>    specification §5.1.2). This is a list of all classes from which the current
>    class can inherit members. Clicking on the ancestors selects which inherited
>    members are listed. If all ancestors are grayed out, only locally defined or
>    overridden members are listed.
>  - Each package has its own page.
>
> Wiki-like syntax in documentation source
> ----------------------------------------
>
> Authors of documentation no longer have to use HTML tags in their comments.
> Instead, Scaladoc supports a wiki-like syntax very similar to that used in Trac.
> In general, Scaladoc authors should no longer use HTML tags in documentation as
> Scaladoc may in the future also generate documentation in other formats than
> HTML.
>
> Wiki syntax is dependent of left-side alignment: the star marking the beginning
> of a Scaladoc line marks the beginning of the left side for parsing purposes
> (start-of-line markers are mandatory). Here is a small example of Scaladoc-
> supported wiki syntax.
>
> /** This is a paragraph
>  *
>  * This is another paragraph (note the empty line above) containing '''bold''',
>  * ''italic'', `monospace`,
>  * __underline__, ^superscript^, and ,,subscript,, words.
>  *
>  * {{{
>  * Multi-line code can be inserted as a block and will be printed as monospace
>  * text.
>  * It isn't parsed as Scala, with keyword highlighting, but may be in the
>  * future.
>  * }}}
>  *
>  * In the near future, wiki syntax will also support bullet or number lists as
>  * well as links to the www and to other pages inside the documentation. */
>
> Compile-time error checking of documentation source
> ---------------------------------------------------
>
> The Scaladoc comment parser will report invalid tags. Valid tags are:
>  - @author (multiple allowed);
>  - @see (multiple allowed);
>  - @return (one allowed);
>  - @throws (one allowed per exception);
>  - @param (one allowed per value parameter);
>  - @tparam (one allowed per type parameter);
>  - @version (one allowed);
>  - @since (one allowed);
>  - @todo (multiple allowed);
>  - @deprecated (multiple allowed).
>
> The Scaladoc comment parser will report invalid wiki syntax, such as unclosed
> formatting ('''bold for example), unclosed code blocks, or missing start-of-line
> markers.
>
> Missing features
> ----------------
>
> Scaladoc 2 is still in development. This is a list of missing features.
>
>  - Documentation:
>    - Inheritance chain of members (definition class, then all overrides) is
>      printed.
>    - Subclasses are printed.
>    - Templates (classes, traits and objects) in types are links.
>    - Each owner element (at the top of the page) is a link.
>    - Documentation source at top of package objects is used by Scaladoc.
>    - Function, Tuple and Product classes are not listed.
>    - More comment tags are printed in the documentation (author, see, since,
>      etc.).
>    - There is a link to the source.
>
>  - Wiki syntax:
>    - Supports link tags.
>    - Supports bullet or number lists.
>
>  - HTML:
>    - Pages works as expected in Internet Explorer 8 & 9 (possibly also 7,
>      certainly not 6).
>    - The right side of the page is more compact, with less padding and smaller
>      text.
>    - The filter tool for packages is easily recognizable for what it is, not
>      just an empty, mysterious space.
>    - There is a filter tool for members.
>    - The filter tool has a better performance for large documentation.
>    - Documentation for members is hidden by default and shown when clicking the
>      signature.
>    - Documentation for value and type parameters is shown when clicking the
>      parameter name.
>
>

1) Non-HTML markup is a major step forward.

2) Frames are ugly, and non-resizable frames uglier if not relics from
another era.

3) Would be nice to have just the package names collapsed and let the
user choose which to expand, in order to view the package members.

4) In the right pane (at least), code-related items should be rendered
in fixed-width font.

5) def reduceRightOption [B ⊳ T] (op: (T, B) ⇒ B) :Option[B]
Is symbol ⊳valid in source code (like ⇒ is)?

BR
Christos

anli
Joined: 2008-08-19,
User offline. Last seen 1 day 58 min ago.
Re: Scaladoc 2

On Wednesday 25 November 2009 12:26:33 Gilles Dubochet wrote:
> Beside usual bug reports, I am interested in feedback concerning the
> usability of Scaladoc. Please, send in use-cases of what you were
> searching for, and why you did or did not find it easily in Scaladoc.
> General feedback about the look and feel of Scaladoc is also wanted.

To my taste:

- all grey backgrounds are too dark
- all colored backgrounds are too saturated
- left frame: line-spacing too small
- left frame: left-padding is absent (letters sticked to window edge)
- divider between left and right frames isn't movable

- left frame: packages list is missed (I see, it is by design, but
to my taste it isn't the best way; probably all packages can be folded
and have '+' button to expand)
- right frame: all code must be monospaced
- right frame: no links to source code
- right frame: have I missed something? - there are no any links
to other items, say, in "def + (elem: A) :Set[A]" "Set" must be
a link, and it must be visible as a link.

Andrew

Jesse Eichar
Joined: 2008-12-20,
User offline. Last seen 42 years 45 weeks ago.
Re: Scaladoc 2
Love it!
Is there a way to get the list of packages or other categories?
If I am exploring a new API with many packages it is useful to be able to list the packages to get an initial overview of the structure of the system.  Then I would dig into the packages that look most interesting.  
Perhaps there could be a special search syntax to list all packages or all objectect, etc...  Or a way to indicate what the search is for.  IE package, object, class, trait, type selector.  (You would need multiple selection most likely). 

Jesse
On Wed, Nov 25, 2009 at 10:26 AM, Gilles Dubochet <gilles [dot] dubochet [at] epfl [dot] ch> wrote:
As of revision 19844, Scaladoc 2 replace the old Scaladoc in all trunk and 2.8
builds. Have a look at the trunk nightly Scaladoc.

http://www.scala-lang.org/archives/downloads/distrib/files/nightly/docs/library/index.html

Scaladoc 2 is a major update to Scaladoc by Manohar Jonnalagedda and Gilles
Dubochet. It is based on the original Scaladoc (Sean McDirmid, Geoffrey
Washburn, Vincent Cremet and Stéphane Michleoud) as well as on vScaladoc (David
Bernard).

Beside usual bug reports, I am interested in feedback concerning the usability
of Scaladoc. Please, send in use-cases of what you were searching for, and why
you did or did not find it easily in Scaladoc. General feedback about the look
and feel of Scaladoc is also wanted.

A new look and feel for documentation pages
-------------------------------------------

The left bar of the documentation page, listing packages and top-level objects,
is simpler. There are no separate lists for packages, classes and objects.
Instead, there is a single list contains packages and their nested classes and
objects. Classes and their companion objects are a single entry in the list. A
text box at the top of the list (look for an empty blank space) allows to
interactively filter the list by entering a package name, class name, or a part
thereof.

The right side of the page, with the documentation for a single class, trait,
object or package, is organized differently. Most notably:
 - All members, inherited or locally defined are listed as actual members (not
   just links to the definition in the super-class), with their types as seen
   from the current class.
 - There is no more distinction between vals, defs, classes, types, etc.
   Instead, members are subdivided into three categories:
   - value members (defs, vals, vars, objects, packages) that result in a value
     (and possibly a side-effect) when they are accessed;
   - type members (traits, classes, abstract types, type aliases) that result
     in a type (and possibly a constructor) when they are accessed;
   - instance constructors for the class.
 - At the top of the members list is a field titled "inherits" that contains
   the linearization of the class's ancestors (see the Scala language
   specification §5.1.2). This is a list of all classes from which the current
   class can inherit members. Clicking on the ancestors selects which inherited
   members are listed. If all ancestors are grayed out, only locally defined or
   overridden members are listed.
 - Each package has its own page.

Wiki-like syntax in documentation source
----------------------------------------

Authors of documentation no longer have to use HTML tags in their comments.
Instead, Scaladoc supports a wiki-like syntax very similar to that used in Trac.
In general, Scaladoc authors should no longer use HTML tags in documentation as
Scaladoc may in the future also generate documentation in other formats than
HTML.

Wiki syntax is dependent of left-side alignment: the star marking the beginning
of a Scaladoc line marks the beginning of the left side for parsing purposes
(start-of-line markers are mandatory). Here is a small example of Scaladoc-
supported wiki syntax.

/** This is a paragraph
 *
 * This is another paragraph (note the empty line above) containing '''bold''',
 * ''italic'', `monospace`,
 * __underline__, ^superscript^, and ,,subscript,, words.
 *
 * {{{
 * Multi-line code can be inserted as a block and will be printed as monospace
 * text.
 * It isn't parsed as Scala, with keyword highlighting, but may be in the
 * future.
 * }}}
 *
 * In the near future, wiki syntax will also support bullet or number lists as
 * well as links to the www and to other pages inside the documentation. */

Compile-time error checking of documentation source
---------------------------------------------------

The Scaladoc comment parser will report invalid tags. Valid tags are:
 - @author (multiple allowed);
 - @see (multiple allowed);
 - @return (one allowed);
 - @throws <exception class> (one allowed per exception);
 - @param <param name> (one allowed per value parameter);
 - @tparam <param name> (one allowed per type parameter);
 - @version (one allowed);
 - @since (one allowed);
 - @todo (multiple allowed);
 - @deprecated (multiple allowed).

The Scaladoc comment parser will report invalid wiki syntax, such as unclosed
formatting ('''bold for example), unclosed code blocks, or missing start-of-line
markers.

Missing features
----------------

Scaladoc 2 is still in development. This is a list of missing features.

 - Documentation:
   - Inheritance chain of members (definition class, then all overrides) is
     printed.
   - Subclasses are printed.
   - Templates (classes, traits and objects) in types are links.
   - Each owner element (at the top of the page) is a link.
   - Documentation source at top of package objects is used by Scaladoc.
   - Function, Tuple and Product classes are not listed.
   - More comment tags are printed in the documentation (author, see, since,
     etc.).
   - There is a link to the source.

 - Wiki syntax:
   - Supports link tags.
   - Supports bullet or number lists.

 - HTML:
   - Pages works as expected in Internet Explorer 8 & 9 (possibly also 7,
     certainly not 6).
   - The right side of the page is more compact, with less padding and smaller
     text.
   - The filter tool for packages is easily recognizable for what it is, not
     just an empty, mysterious space.
   - There is a filter tool for members.
   - The filter tool has a better performance for large documentation.
   - Documentation for members is hidden by default and shown when clicking the
     signature.
   - Documentation for value and type parameters is shown when clicking the
     parameter name.


Kevin Wright
Joined: 2009-06-09,
User offline. Last seen 49 weeks 3 days ago.
Re: Scaladoc 2
Can you drop case sensitivity on the search box, and also support eclipse-style CamelCase searches?i.e. NPE matches NullPointerException, ISR matches InputStreamReader, etc.
I'd also love if I could show:
  • implicits available for the class (both conversions to and from)
  • for a trait, the self type and other traits with the same self type

Other design suggestions:
  • Hide member documentation by default (except the signature), use an accordion-style control to show it on request
  • Use different colour icons for classes and traits
  • Possibly use different icons for abstract and concrete classes
  • On the "Inherits" list, show relevant trait/classs icon for each superclass



On Wed, Nov 25, 2009 at 10:11 AM, Andrew Gaydenko <a [at] gaydenko [dot] com> wrote:
On Wednesday 25 November 2009 12:26:33 Gilles Dubochet wrote:
> Beside usual bug reports, I am interested in feedback concerning the
>  usability of Scaladoc. Please, send in use-cases of what you were
>  searching for, and why you did or did not find it easily in Scaladoc.
>  General feedback about the look and feel of Scaladoc is also wanted.

To my taste:

- all grey backgrounds are too dark
- all colored backgrounds are too saturated
- left frame: line-spacing too small
- left frame: left-padding is absent (letters sticked to window edge)
- divider between left and right frames isn't movable

- left frame: packages list is missed (I see, it is by design, but
 to my taste it isn't the best way; probably all packages can be folded
 and have '+' button to expand)
- right frame: all code must be monospaced
- right frame: no links to source code
- right frame: have I missed something? - there are no any links
 to other items, say, in "def + (elem: A) :Set[A]" "Set" must be
 a link, and it must be visible as a link.


Andrew

dubochet
Joined: 2008-06-30,
User offline. Last seen 1 year 36 weeks ago.
Re: Scaladoc 2

Hello Christos.

> 1) Non-HTML markup is a major step forward.
>
> 2) Frames are ugly, and non-resizable frames uglier if not relics from
> another era.

I agree. But what other solution would you propose? I'd love to have a better design for that bar.

As for the non-resizable frame, that's something to change, I agree. It probably involves JavaScript wizardry. Contributions are more than welcome.

> 3) Would be nice to have just the package names collapsed and let the
> user choose which to expand, in order to view the package members.

Yes, I think that Jesse is asking for something similar. I will add it to the missing features list.

https://lampsvn.epfl.ch/trac/scala/wiki/Scaladoc

> 4) In the right pane (at least), code-related items should be rendered
> in fixed-width font.

Do you mean code elements in documentation, or signatures?

> 5) def reduceRightOption [B ⊳ T] (op: (T, B) ⇒ B) :Option[B]
> Is symbol ⊳valid in source code (like ⇒ is)?

Euh, sorry, no. I need to change that.

Thanks for your remarks,
Gilles.

dcsobral
Joined: 2009-04-23,
User offline. Last seen 38 weeks 5 days ago.
Re: Scaladoc 2
The documentation isn't building on windows right now. It fails trying to create the file "::.html", which, for obvious reasons, it will never be able to.

On Wed, Nov 25, 2009 at 7:26 AM, Gilles Dubochet <gilles [dot] dubochet [at] epfl [dot] ch> wrote:
As of revision 19844, Scaladoc 2 replace the old Scaladoc in all trunk and 2.8
builds. Have a look at the trunk nightly Scaladoc.

http://www.scala-lang.org/archives/downloads/distrib/files/nightly/docs/library/index.html

Scaladoc 2 is a major update to Scaladoc by Manohar Jonnalagedda and Gilles
Dubochet. It is based on the original Scaladoc (Sean McDirmid, Geoffrey
Washburn, Vincent Cremet and Stéphane Michleoud) as well as on vScaladoc (David
Bernard).

Beside usual bug reports, I am interested in feedback concerning the usability
of Scaladoc. Please, send in use-cases of what you were searching for, and why
you did or did not find it easily in Scaladoc. General feedback about the look
and feel of Scaladoc is also wanted.

A new look and feel for documentation pages
-------------------------------------------

The left bar of the documentation page, listing packages and top-level objects,
is simpler. There are no separate lists for packages, classes and objects.
Instead, there is a single list contains packages and their nested classes and
objects. Classes and their companion objects are a single entry in the list. A
text box at the top of the list (look for an empty blank space) allows to
interactively filter the list by entering a package name, class name, or a part
thereof.

The right side of the page, with the documentation for a single class, trait,
object or package, is organized differently. Most notably:
 - All members, inherited or locally defined are listed as actual members (not
   just links to the definition in the super-class), with their types as seen
   from the current class.
 - There is no more distinction between vals, defs, classes, types, etc.
   Instead, members are subdivided into three categories:
   - value members (defs, vals, vars, objects, packages) that result in a value
     (and possibly a side-effect) when they are accessed;
   - type members (traits, classes, abstract types, type aliases) that result
     in a type (and possibly a constructor) when they are accessed;
   - instance constructors for the class.
 - At the top of the members list is a field titled "inherits" that contains
   the linearization of the class's ancestors (see the Scala language
   specification §5.1.2). This is a list of all classes from which the current
   class can inherit members. Clicking on the ancestors selects which inherited
   members are listed. If all ancestors are grayed out, only locally defined or
   overridden members are listed.
 - Each package has its own page.

Wiki-like syntax in documentation source
----------------------------------------

Authors of documentation no longer have to use HTML tags in their comments.
Instead, Scaladoc supports a wiki-like syntax very similar to that used in Trac.
In general, Scaladoc authors should no longer use HTML tags in documentation as
Scaladoc may in the future also generate documentation in other formats than
HTML.

Wiki syntax is dependent of left-side alignment: the star marking the beginning
of a Scaladoc line marks the beginning of the left side for parsing purposes
(start-of-line markers are mandatory). Here is a small example of Scaladoc-
supported wiki syntax.

/** This is a paragraph
 *
 * This is another paragraph (note the empty line above) containing '''bold''',
 * ''italic'', `monospace`,
 * __underline__, ^superscript^, and ,,subscript,, words.
 *
 * {{{
 * Multi-line code can be inserted as a block and will be printed as monospace
 * text.
 * It isn't parsed as Scala, with keyword highlighting, but may be in the
 * future.
 * }}}
 *
 * In the near future, wiki syntax will also support bullet or number lists as
 * well as links to the www and to other pages inside the documentation. */

Compile-time error checking of documentation source
---------------------------------------------------

The Scaladoc comment parser will report invalid tags. Valid tags are:
 - @author (multiple allowed);
 - @see (multiple allowed);
 - @return (one allowed);
 - @throws <exception class> (one allowed per exception);
 - @param <param name> (one allowed per value parameter);
 - @tparam <param name> (one allowed per type parameter);
 - @version (one allowed);
 - @since (one allowed);
 - @todo (multiple allowed);
 - @deprecated (multiple allowed).

The Scaladoc comment parser will report invalid wiki syntax, such as unclosed
formatting ('''bold for example), unclosed code blocks, or missing start-of-line
markers.

Missing features
----------------

Scaladoc 2 is still in development. This is a list of missing features.

 - Documentation:
   - Inheritance chain of members (definition class, then all overrides) is
     printed.
   - Subclasses are printed.
   - Templates (classes, traits and objects) in types are links.
   - Each owner element (at the top of the page) is a link.
   - Documentation source at top of package objects is used by Scaladoc.
   - Function, Tuple and Product classes are not listed.
   - More comment tags are printed in the documentation (author, see, since,
     etc.).
   - There is a link to the source.

 - Wiki syntax:
   - Supports link tags.
   - Supports bullet or number lists.

 - HTML:
   - Pages works as expected in Internet Explorer 8 & 9 (possibly also 7,
     certainly not 6).
   - The right side of the page is more compact, with less padding and smaller
     text.
   - The filter tool for packages is easily recognizable for what it is, not
     just an empty, mysterious space.
   - There is a filter tool for members.
   - The filter tool has a better performance for large documentation.
   - Documentation for members is hidden by default and shown when clicking the
     signature.
   - Documentation for value and type parameters is shown when clicking the
     parameter name.




--
Daniel C. Sobral

Veni, vidi, veterni.
loverdos
Joined: 2008-11-18,
User offline. Last seen 2 years 27 weeks ago.
Re: Scaladoc 2

Hi Gilles,

On Wed, Nov 25, 2009 at 12:48, Gilles Dubochet wrote:
> Hello Christos.
>
>> 1) Non-HTML markup is a major step forward.
>>
>> 2) Frames are ugly, and non-resizable frames uglier if not relics from
>> another era.
>
> I agree. But what other solution would you propose? I'd love to have a better design for that bar.
>
> As for the non-resizable frame, that's something to change, I agree. It probably involves JavaScript wizardry. Contributions are more than welcome.

Something CSS-related that would make everything fit into one page?.
Could we broadcast this to scala/scala-user and ask for some
expertise? For example, it seems that python does not use frames.

http://docs.python.org/library/os.html

>
>> 3) Would be nice to have just the package names collapsed and let the
>> user choose which to expand, in order to view the package members.
>
> Yes, I think that Jesse is asking for something similar. I will add it to the missing features list.
>
> https://lampsvn.epfl.ch/trac/scala/wiki/Scaladoc
>
>> 4) In the right pane (at least), code-related items should be rendered
>> in fixed-width font.
>
> Do you mean code elements in documentation, or signatures?
>
>> 5) def reduceRightOption [B ⊳ T] (op: (T, B) ⇒ B) :Option[B]
>> Is symbol ⊳valid in source code (like ⇒ is)?
>
> Euh, sorry, no. I need to change that.
>
> Thanks for your remarks,
> Gilles.

BR
Christos.

dubochet
Joined: 2008-06-30,
User offline. Last seen 1 year 36 weeks ago.
Re: Scaladoc 2

Hello.

> Can you drop case sensitivity on the search box, and also support eclipse-style CamelCase searches?
> i.e. NPE matches NullPointerException, ISR matches InputStreamReader, etc.

In the medium-term, the filtering language will certainly be improved. Contributions are, as always, very welcome.

I am not sure about case sensitivity. The argument in favour is that symbols are case sensitive in Scala. The argument against (I think) is that camel-case makes is hard to know how a sub-part of a name will be capitalised. I don't mind changing the current behaviour, but I'd like to hear your arguments.

> I'd also love if I could show:
> • implicits available for the class (both conversions to and from)

I definitely want to add conversions from. As for conversions to, I am less sure as to when that would be useful. Do you have a use case?

> • for a trait, the self type and other traits with the same self type

Oh yes, the self type is something to add. I added it to the missing features list.

https://lampsvn.epfl.ch/trac/scala/wiki/Scaladoc

As for traits with the same self type, I am not sure that I understand why this would be useful. And what is "the same": exactly the same type, or a subtype thereof? Do you have a use case?

> Other design suggestions:
> • Hide member documentation by default (except the signature), use an accordion-style control to show it on request

This is already in the missing features list.

> • Use different colour icons for classes and traits

I am not sure about this one. Classes and traits are identical, for most uses of a library. Currently, the colour scheme is used to differentiate between values (objects, packages, and value members) and types (traits, classes, and type members). People probably aren't used to that use of colour yet, but I hope it will become useful.

> • Possibly use different icons for abstract and concrete classes

Mmmh. I'll have to think about that.

> • On the "Inherits" list, show relevant trait/classs icon for each superclass

Oh, yes, I ought to do that, you are right. I added it to the missing features list.

Cheers,
Gilles.

dubochet
Joined: 2008-06-30,
User offline. Last seen 1 year 36 weeks ago.
Re: Scaladoc 2

Hello Christos.

>>> 2) Frames are ugly, and non-resizable frames uglier if not relics from
>>> another era.
>>
>> I agree. But what other solution would you propose? I'd love to have a better design for that bar.
>>
>> As for the non-resizable frame, that's something to change, I agree. It probably involves JavaScript wizardry. Contributions are more than welcome.
>
> Something CSS-related that would make everything fit into one page?.
> Could we broadcast this to scala/scala-user and ask for some
> expertise?

I sent it to Scala internals in order to get a first round of feedback before sending it to the wider community. If you don't mind, Christos, I'd like to wait a few days before sending it to a wider-audience list.

> For example, it seems that python does not use frames.
>
> http://docs.python.org/library/os.html

You really prefer the python bar? It isn't resizable either, and because it scrolls with the rest of the page, it looses context whenever the right-side documentation is moved.

Frames may not be very fashionable nowadays (although, technically, Scaladoc no longer uses frames but iframes). Still, what they offer — multiple sub-pages each with their own viewing context — is very useful and difficult to duplicate using DIVs and CSS.

Don't hesitate to send in other ideas on how to improve the left bar, or additional argument to convince me that a static Python-like bar is the way to go.

Cheers,
Gilles.

Michal Politowski 2
Joined: 2009-09-15,
User offline. Last seen 42 years 45 weeks ago.
Re: Scaladoc 2

On Wed, 25 Nov 2009 10:26:33 +0100, Gilles Dubochet wrote:
> As of revision 19844, Scaladoc 2 replace the old Scaladoc in all trunk and 2.8
> builds. Have a look at the trunk nightly Scaladoc.
>
> http://www.scala-lang.org/archives/downloads/distrib/files/nightly/docs/...
>
> Scaladoc 2 is a major update to Scaladoc by Manohar Jonnalagedda and Gilles
> Dubochet. It is based on the original Scaladoc (Sean McDirmid, Geoffrey
> Washburn, Vincent Cremet and Stéphane Michleoud) as well as on vScaladoc (David
> Bernard).

Looks very good already.
Is displaying documentation for Any, AnyVal, Null, Nothing on the todo list?

> Missing features
> ----------------
[...]
> - Function, Tuple and Product classes are not listed.

I know that there are many of these, but would that mean their documentation
is totally unavailable?

dubochet
Joined: 2008-06-30,
User offline. Last seen 1 year 36 weeks ago.
Re: Scaladoc 2

Hello Michał:

>> As of revision 19844, Scaladoc 2 replace the old Scaladoc in all trunk and 2.8
>> builds. Have a look at the trunk nightly Scaladoc.
>>
>> http://www.scala-lang.org/archives/downloads/distrib/files/nightly/docs/...
>>
>> Scaladoc 2 is a major update to Scaladoc by Manohar Jonnalagedda and Gilles
>> Dubochet. It is based on the original Scaladoc (Sean McDirmid, Geoffrey
>> Washburn, Vincent Cremet and Stéphane Michleoud) as well as on vScaladoc (David
>> Bernard).
>
> Looks very good already.

Thanks :)

> Is displaying documentation for Any, AnyVal, Null, Nothing on the todo list?

It wasn't. It is now. Thanks for mentioning them.

>> Missing features
>> ----------------
> [...]
>> - Function, Tuple and Product classes are not listed.
>
> I know that there are many of these, but would that mean their documentation
> is totally unavailable?

The current idea is to hide them until filtering the class list by their name. For example, when filtering for "Funct", only Function, Function0, Function1, and PartialFunction would be listed. When filtering for "Function", all the FunctionX classes would appear.

Cheers,
Gilles.

loverdos
Joined: 2008-11-18,
User offline. Last seen 2 years 27 weeks ago.
Re: Scaladoc 2

Hi Gilles,

On Wed, Nov 25, 2009 at 14:40, Gilles Dubochet wrote:
> Hello Christos.
>
>>>> 2) Frames are ugly, and non-resizable frames uglier if not relics from
>>>> another era.
>>>
>>> I agree. But what other solution would you propose? I'd love to have a better design for that bar.
>>>
>>> As for the non-resizable frame, that's something to change, I agree. It probably involves JavaScript wizardry. Contributions are more than welcome.
>>
>> Something CSS-related that would make everything fit into one page?.
>> Could we broadcast this to scala/scala-user and ask for some
>> expertise?
>
> I sent it to Scala internals in order to get a first round of feedback before sending it to the wider community. If you don't mind, Christos, I'd like to wait a few days before sending it to a wider-audience list.

Sure, it's your call.

>
>> For example, it seems that python does not use frames.
>>
>> http://docs.python.org/library/os.html
>
> You really prefer the python bar? It isn't resizable either, and because it scrolls with the rest of the page, it looses context whenever the right-side documentation is moved.
>
> Frames may not be very fashionable nowadays (although, technically, Scaladoc no longer uses frames but iframes). Still, what they offer — multiple sub-pages each with their own viewing context — is very useful and difficult to duplicate using DIVs and CSS.
>
> Don't hesitate to send in other ideas on how to improve the left bar, or additional argument to convince me that a static Python-like bar is the way to go.

Well, I meant it as "let's have a look at what other people have done"
actually.

One aesthetic point that could make a small but noticeable difference
would be to drop the border line between left & right panes and give
the right pane a small margin on the left, so that letters do not
start directly from the scrollbar.

BR
Christos

Johannes Rudolph
Joined: 2008-12-17,
User offline. Last seen 29 weeks 20 hours ago.
Re: Scaladoc 2

I addressed three of the points mentioned wrt the filter-box:

* camel case filtering (many are used to it because at least with
Eclipse that's a standard way to access elements)
* a default text for the filter box, I overlooked it, too, before it
was mentioned here
* an accesskey, so the box can be used only with the keyboard

See the commits in this branch:

http://github.com/jrudolph/scala/commits/scaladoc2-better-filter

Johannes

On Wed, Nov 25, 2009 at 2:33 PM, Christos KK Loverdos
wrote:
> Hi Gilles,
>
> On Wed, Nov 25, 2009 at 14:40, Gilles Dubochet wrote:
>> Hello Christos.
>>
>>>>> 2) Frames are ugly, and non-resizable frames uglier if not relics from
>>>>> another era.
>>>>
>>>> I agree. But what other solution would you propose? I'd love to have a better design for that bar.
>>>>
>>>> As for the non-resizable frame, that's something to change, I agree. It probably involves JavaScript wizardry. Contributions are more than welcome.
>>>
>>> Something CSS-related that would make everything fit into one page?.
>>> Could we broadcast this to scala/scala-user and ask for some
>>> expertise?
>>
>> I sent it to Scala internals in order to get a first round of feedback before sending it to the wider community. If you don't mind, Christos, I'd like to wait a few days before sending it to a wider-audience list.
>
> Sure, it's your call.
>
>>
>>> For example, it seems that python does not use frames.
>>>
>>> http://docs.python.org/library/os.html
>>
>> You really prefer the python bar? It isn't resizable either, and because it scrolls with the rest of the page, it looses context whenever the right-side documentation is moved.
>>
>> Frames may not be very fashionable nowadays (although, technically, Scaladoc no longer uses frames but iframes). Still, what they offer — multiple sub-pages each with their own viewing context — is very useful and difficult to duplicate using DIVs and CSS.
>>
>> Don't hesitate to send in other ideas on how to improve the left bar, or additional argument to convince me that a static Python-like bar is the way to go.
>
> Well, I meant it as "let's have a look at what other people have done"
> actually.
>
> One aesthetic point that could make a small but noticeable difference
> would be to drop the border line between left & right panes and give
> the right pane a small margin on the left, so that letters do not
> start directly from the scrollbar.
>
> BR
> Christos
> --
>  __~O
>  -\ <,       Christos KK Loverdos
> (*)/ (*)      http://ckkloverdos.com
>

dcsobral
Joined: 2009-04-23,
User offline. Last seen 38 weeks 5 days ago.
Re: Scaladoc 2
I'm keeping an open mind wrt the missing features, but, my general impression is: I hate it. Granted, I have always found scaladoc superior to vscaladoc.   So, by parts. First, browsing packages is impossible. It is fortunate that Scala's library is, so far, very poor in most respects, which decreases a bit the sheer size of the listing on the left. There's a search feature, which is fine if you have a hand on the keyboard and know the name of what you are looking for. Having everything collapsed by default would be a huge improvement and, perhaps, even make up for the lack of the third frame.   Speaking of frames and search, because it isn't on a separate frame, I need to scroll to get back to it.   On the other side, I can't click on any of the classes that are being inherited. I would never find that scala.collection.mutable.Stack inherits from scala.collection.seq instead of scala.collection.mutable.seq with this doc.   The full inheritance list is very nice. That they can be clicked to show/remove the members from each is interesting, though non-obvious. It would be better if I could toggle all on/all off, as I have much more use for seeing just a few or all of the members than most of the members.   The method display, again, is horrible to browse, because it includes the description for the method. Granted that most methods in Scala have pitiful descriptions, but one just has to go to a class well documented to see how bad it is. If the description was collapsable, it might be better. Particular if there was an option to collapse/uncollapse all.   And, for all the extraneous information that is presented when one wants to browse, not enough information is presented. I suggest one compares scaladoc and scaladoc 2 for the Regex class, for instance.   On presentation aspect, I hope it is clear that it sucks. The type signature is almost obscured, while we are proudly informed that it is a "def" or a "val", just to name one thing. Honestly, it is in serious need of a CSS wizard. Things like collapsing sections do not even need javascript at all.   And, of course, there are all those things that are missing, which I won't complain about because they were acknowledged.
I use the Scala API documentation a lot. It is my opinion, as a heavy user of these docs, that in its present state, scaladoc 2 is a huge step back.   This *IS* a beta for Scala 2.8, and I'm fully aware rewrites usually set back the state of the art for a while. But I truly hope a LOT of improvement if this is to be released with Scala 2.8.
On Wed, Nov 25, 2009 at 7:26 AM, Gilles Dubochet <gilles [dot] dubochet [at] epfl [dot] ch> wrote:
As of revision 19844, Scaladoc 2 replace the old Scaladoc in all trunk and 2.8
builds. Have a look at the trunk nightly Scaladoc.

http://www.scala-lang.org/archives/downloads/distrib/files/nightly/docs/library/index.html

Scaladoc 2 is a major update to Scaladoc by Manohar Jonnalagedda and Gilles
Dubochet. It is based on the original Scaladoc (Sean McDirmid, Geoffrey
Washburn, Vincent Cremet and Stéphane Michleoud) as well as on vScaladoc (David
Bernard).

Beside usual bug reports, I am interested in feedback concerning the usability
of Scaladoc. Please, send in use-cases of what you were searching for, and why
you did or did not find it easily in Scaladoc. General feedback about the look
and feel of Scaladoc is also wanted.

A new look and feel for documentation pages
-------------------------------------------

The left bar of the documentation page, listing packages and top-level objects,
is simpler. There are no separate lists for packages, classes and objects.
Instead, there is a single list contains packages and their nested classes and
objects. Classes and their companion objects are a single entry in the list. A
text box at the top of the list (look for an empty blank space) allows to
interactively filter the list by entering a package name, class name, or a part
thereof.

The right side of the page, with the documentation for a single class, trait,
object or package, is organized differently. Most notably:
 - All members, inherited or locally defined are listed as actual members (not
   just links to the definition in the super-class), with their types as seen
   from the current class.
 - There is no more distinction between vals, defs, classes, types, etc.
   Instead, members are subdivided into three categories:
   - value members (defs, vals, vars, objects, packages) that result in a value
     (and possibly a side-effect) when they are accessed;
   - type members (traits, classes, abstract types, type aliases) that result
     in a type (and possibly a constructor) when they are accessed;
   - instance constructors for the class.
 - At the top of the members list is a field titled "inherits" that contains
   the linearization of the class's ancestors (see the Scala language
   specification §5.1.2). This is a list of all classes from which the current
   class can inherit members. Clicking on the ancestors selects which inherited
   members are listed. If all ancestors are grayed out, only locally defined or
   overridden members are listed.
 - Each package has its own page.

Wiki-like syntax in documentation source
----------------------------------------

Authors of documentation no longer have to use HTML tags in their comments.
Instead, Scaladoc supports a wiki-like syntax very similar to that used in Trac.
In general, Scaladoc authors should no longer use HTML tags in documentation as
Scaladoc may in the future also generate documentation in other formats than
HTML.

Wiki syntax is dependent of left-side alignment: the star marking the beginning
of a Scaladoc line marks the beginning of the left side for parsing purposes
(start-of-line markers are mandatory). Here is a small example of Scaladoc-
supported wiki syntax.

/** This is a paragraph
 *
 * This is another paragraph (note the empty line above) containing '''bold''',
 * ''italic'', `monospace`,
 * __underline__, ^superscript^, and ,,subscript,, words.
 *
 * {{{
 * Multi-line code can be inserted as a block and will be printed as monospace
 * text.
 * It isn't parsed as Scala, with keyword highlighting, but may be in the
 * future.
 * }}}
 *
 * In the near future, wiki syntax will also support bullet or number lists as
 * well as links to the www and to other pages inside the documentation. */

Compile-time error checking of documentation source
---------------------------------------------------

The Scaladoc comment parser will report invalid tags. Valid tags are:
 - @author (multiple allowed);
 - @see (multiple allowed);
 - @return (one allowed);
 - @throws <exception class> (one allowed per exception);
 - @param <param name> (one allowed per value parameter);
 - @tparam <param name> (one allowed per type parameter);
 - @version (one allowed);
 - @since (one allowed);
 - @todo (multiple allowed);
 - @deprecated (multiple allowed).

The Scaladoc comment parser will report invalid wiki syntax, such as unclosed
formatting ('''bold for example), unclosed code blocks, or missing start-of-line
markers.

Missing features
----------------

Scaladoc 2 is still in development. This is a list of missing features.

 - Documentation:
   - Inheritance chain of members (definition class, then all overrides) is
     printed.
   - Subclasses are printed.
   - Templates (classes, traits and objects) in types are links.
   - Each owner element (at the top of the page) is a link.
   - Documentation source at top of package objects is used by Scaladoc.
   - Function, Tuple and Product classes are not listed.
   - More comment tags are printed in the documentation (author, see, since,
     etc.).
   - There is a link to the source.

 - Wiki syntax:
   - Supports link tags.
   - Supports bullet or number lists.

 - HTML:
   - Pages works as expected in Internet Explorer 8 & 9 (possibly also 7,
     certainly not 6).
   - The right side of the page is more compact, with less padding and smaller
     text.
   - The filter tool for packages is easily recognizable for what it is, not
     just an empty, mysterious space.
   - There is a filter tool for members.
   - The filter tool has a better performance for large documentation.
   - Documentation for members is hidden by default and shown when clicking the
     signature.
   - Documentation for value and type parameters is shown when clicking the
     parameter name.




--
Daniel C. Sobral

Veni, vidi, veterni.
dcsobral
Joined: 2009-04-23,
User offline. Last seen 38 weeks 5 days ago.
Re: Scaladoc 2
On Wed, Nov 25, 2009 at 11:20 AM, Gilles Dubochet <gilles [dot] dubochet [at] epfl [dot] ch> wrote:
Hello Michał:

> I know that there are many of these, but would that mean their documentation
> is totally unavailable?

The current idea is to hide them until filtering the class list by their name. For example, when filtering for "Funct", only Function, Function0, Function1, and PartialFunction would be listed. When filtering for "Function", all the FunctionX classes would appear.

And the user is supposed to first read the old scaladoc to know these classes exist, and then go to the new scaladoc, is it?


--
Daniel C. Sobral

Veni, vidi, veterni.
dubochet
Joined: 2008-06-30,
User offline. Last seen 1 year 36 weeks ago.
Re: Scaladoc 2

Daniel.

As you note in your email, Scaladoc 2 is not finished yet. I am sorry to hear that you hate it in its current state. However, as I point out below, almost all of your complaints about Scaladoc are listed missing features. I added the detailed missing features list at the end of my original email to make it clear that I was aware of the rough edges Scaladoc 2 still has, and that I am actively working to smooth them out.

https://lampsvn.epfl.ch/trac/scala/wiki/Scaladoc

Scaladoc 2 had to be committed to trunk so that documentation for the new 2.8 libraries can be written using the wiki syntax. Also, I hope that by moving the source of Scaladoc 2 to trunk, it will make contributions easier. Maybe you would like to contribute fixes for some of the issues you mention below?

> I'm keeping an open mind wrt the missing features, but, my general impression is: I hate it. Granted, I have always found scaladoc superior to vscaladoc.
>
> So, by parts. First, browsing packages is impossible. It is fortunate that Scala's library is, so far, very poor in most respects, which decreases a bit the sheer size of the listing on the left. There's a search feature, which is fine if you have a hand on the keyboard and know the name of what you are looking for. Having everything collapsed by default would be a huge improvement and, perhaps, even make up for the lack of the third frame.

On the todo list.

> Speaking of frames and search, because it isn't on a separate frame, I need to scroll to get back to it.

Added to the todo list.

> On the other side, I can't click on any of the classes that are being inherited. I would never find that scala.collection.mutable.Stack inherits from scala.collection.seq instead of scala.collection.mutable.seq with this doc.

On the todo list.

> The full inheritance list is very nice. That they can be clicked to show/remove the members from each is interesting, though non-obvious. It would be better if I could toggle all on/all off, as I have much more use for seeing just a few or all of the members than most of the members.

I guess that will be implemented at some point in the future. Contributions are welcome.

> The method display, again, is horrible to browse, because it includes the description for the method. Granted that most methods in Scala have pitiful descriptions, but one just has to go to a class well documented to see how bad it is. If the description was collapsable, it might be better. Particular if there was an option to collapse/uncollapse all.

On the todo list.

> And, for all the extraneous information that is presented when one wants to browse, not enough information is presented. I suggest one compares scaladoc and scaladoc 2 for the Regex class, for instance.

Is there something missing that isn't on the todo list?

> On presentation aspect, I hope it is clear that it sucks. The type signature is almost obscured, while we are proudly informed that it is a "def" or a "val", just to name one thing. Honestly, it is in serious need of a CSS wizard. Things like collapsing sections do not even need javascript at all.

What do you mean by "almost obscured"? On my machine, it all looks quite readable.

> And, of course, there are all those things that are missing, which I won't complain about because they were acknowledged.
> I use the Scala API documentation a lot. It is my opinion, as a heavy user of these docs, that in its present state, scaladoc 2 is a huge step back.
>
> This *IS* a beta for Scala 2.8, and I'm fully aware rewrites usually set back the state of the art for a while. But I truly hope a LOT of improvement if this is to be released with Scala 2.8.

Sincerely,
Gilles.

Blair Zajac
Joined: 2009-01-12,
User offline. Last seen 42 years 45 weeks ago.
Re: Scaladoc 2

On Nov 25, 2009, at 1:26 AM, Gilles Dubochet wrote:

> As of revision 19844, Scaladoc 2 replace the old Scaladoc in all trunk and 2.8
> builds. Have a look at the trunk nightly Scaladoc.
>
> http://www.scala-lang.org/archives/downloads/distrib/files/nightly/docs/...

Nice work.

In the "inherits" section at the top I would like to see classes/traits be links the the documentation. Listing subclasses and subtraits that extend whatever you're looking at is also very useful when you're trying to decide which implementation of an interface to use. The list of subclasses and subtraits should not be limited just to to sealed traits/classes.

I find scrolling the left bar to find the section of classes takes too long. I like what GotApi did with their JavaDocs where you can expand or collapse packages and then click on the class you want:

http://www.gotapi.com/java15

Regards,
Blair

Kevin Wright
Joined: 2009-06-09,
User offline. Last seen 49 weeks 3 days ago.
Re: Scaladoc 2


On Wed, Nov 25, 2009 at 12:21 PM, Gilles Dubochet <gilles [dot] dubochet [at] epfl [dot] ch> wrote:
Hello.

> Can you drop case sensitivity on the search box, and also support eclipse-style CamelCase searches?
> i.e. NPE matches NullPointerException, ISR matches InputStreamReader, etc.

In the medium-term, the filtering language will certainly be improved. Contributions are, as always, very welcome.

I am not sure about case sensitivity. The argument in favour is that symbols are case sensitive in Scala. The argument against (I think) is that camel-case makes is hard to know how a sub-part of a name will be capitalised. I don't mind changing the current behaviour, but I'd like to hear your arguments.

There's no need, you already figured out my arguments :) 
> I'd also love if I could show:
>       • implicits available for the class (both conversions to and from)

I definitely want to add conversions from. As for conversions to, I am less sure as to when that would be useful. Do you have a use case?

I was thinking of any class intended for extending methods via the pimp-my-library pattern. Naming such classes RichXxxx is ideal, but may not always be viable.Although this one is easily resolved with the hand-written part of the scaladoc
 
>       • for a trait, the self type and other traits with the same self type

Oh yes, the self type is something to add. I added it to the missing features list.

https://lampsvn.epfl.ch/trac/scala/wiki/Scaladoc

As for traits with the same self type, I am not sure that I understand why this would be useful. And what is "the same": exactly the same type, or a subtype thereof? Do you have a use case?

I was thinking specifically of the hydra-like collection of traits in the compiler, all of which have Global as a self-type.Maybe a better solution would be if the documentation for class Foo listed all traits having Foo as the self-type, instead of showing self-peers

 
> Other design suggestions:
>       • Hide member documentation by default (except the signature), use an accordion-style control to show it on request

This is already in the missing features list.

>       • Use different colour icons for classes and traits

I am not sure about this one. Classes and traits are identical, for most uses of a library. Currently, the colour scheme is used to differentiate between values (objects, packages, and value members) and types (traits, classes, and type members). People probably aren't used to that use of colour yet, but I hope it will become useful.

This wasn't a big issue for me, but I find that the usage patterns of traits and classes tend to be different

 
>       • Possibly use different icons for abstract and concrete classes

Mmmh. I'll have to think about that.

>       • On the "Inherits" list, show relevant trait/classs icon for each superclass

Oh, yes, I ought to do that, you are right. I added it to the missing features list.

Cheers,
Gilles.

Dean Wampler
Joined: 2008-12-26,
User offline. Last seen 42 years 45 weeks ago.
Re: Scaladoc 2
A few features I consider essential.
1) Links to the underlying source files. It's invaluable to be able to browse the source occasionally.
2) "index" of all methods in all types. This is something I really found useful in Javadocs and I've missed in Scaladocs. Sometimes I don't know where a method is defined or declared and the fastest way to find out is to look at the index of methods.
3) Show known subclasses/subtraitsSomeone else mentioned this feature in this thread.
Concerning the left-hand navigation, I prefer to see all types in alphabetical order, independent of their package location. When I care about package location, I click the package link in the old Scaladocs format.
Thanks for the hard work!dean

On Wed, Nov 25, 2009 at 3:26 AM, Gilles Dubochet <gilles [dot] dubochet [at] epfl [dot] ch> wrote:
As of revision 19844, Scaladoc 2 replace the old Scaladoc in all trunk and 2.8
builds. Have a look at the trunk nightly Scaladoc.

http://www.scala-lang.org/archives/downloads/distrib/files/nightly/docs/library/index.html

Scaladoc 2 is a major update to Scaladoc by Manohar Jonnalagedda and Gilles
Dubochet. It is based on the original Scaladoc (Sean McDirmid, Geoffrey
Washburn, Vincent Cremet and Stéphane Michleoud) as well as on vScaladoc (David
Bernard).
...


--
Dean Wampler
coauthor of "Programming Scala" (O'Reilly)
-  http://programmingscala.com

twitter: @deanwampler, @chicagoscala
blog: http://blog.polyglotprogramming.com
Chicago-Area Scala Enthusiasts (CASE):
-  http://groups.google.com/group/chicagoscala
-  http://www.meetup.com/chicagoscala/ (Meetings)
http://www.linkedin.com/in/deanwampler
http://www.polyglotprogramming.com
http://aquarium.rubyforge.org
http://www.contract4j.org
Kevin Wright
Joined: 2009-06-09,
User offline. Last seen 49 weeks 3 days ago.
Re: Scaladoc 2
For the sake of contributing bug fixes and enhancements...Are you working on this directly against svn, or do you have a git clone someplace?
Kevin Wright
Joined: 2009-06-09,
User offline. Last seen 49 weeks 3 days ago.
Re: Scaladoc 2

On Wed, Nov 25, 2009 at 11:31 AM, Daniel Sobral <dcsobral [at] gmail [dot] com> wrote:
The documentation isn't building on windows right now. It fails trying to create the file "::.html", which, for obvious reasons, it will never be able to.

This has now become a blocker for me. A standard full build of libraries + eclipse plugin includes the documentation target, but I'm unfortunately on a windows box...
As I'm actively testing integration of my compiler plugin with the eclipse plugin, I'm having to build my own from trunk and can't just use the nightlies. Please put this bug at the top of your list!
 

On Wed, Nov 25, 2009 at 7:26 AM, Gilles Dubochet <gilles [dot] dubochet [at] epfl [dot] ch> wrote:
As of revision 19844, Scaladoc 2 replace the old Scaladoc in all trunk and 2.8
builds. Have a look at the trunk nightly Scaladoc.

http://www.scala-lang.org/archives/downloads/distrib/files/nightly/docs/library/index.html

Scaladoc 2 is a major update to Scaladoc by Manohar Jonnalagedda and Gilles
Dubochet. It is based on the original Scaladoc (Sean McDirmid, Geoffrey
Washburn, Vincent Cremet and Stéphane Michleoud) as well as on vScaladoc (David
Bernard).

Beside usual bug reports, I am interested in feedback concerning the usability
of Scaladoc. Please, send in use-cases of what you were searching for, and why
you did or did not find it easily in Scaladoc. General feedback about the look
and feel of Scaladoc is also wanted.

A new look and feel for documentation pages
-------------------------------------------

The left bar of the documentation page, listing packages and top-level objects,
is simpler. There are no separate lists for packages, classes and objects.
Instead, there is a single list contains packages and their nested classes and
objects. Classes and their companion objects are a single entry in the list. A
text box at the top of the list (look for an empty blank space) allows to
interactively filter the list by entering a package name, class name, or a part
thereof.

The right side of the page, with the documentation for a single class, trait,
object or package, is organized differently. Most notably:
 - All members, inherited or locally defined are listed as actual members (not
   just links to the definition in the super-class), with their types as seen
   from the current class.
 - There is no more distinction between vals, defs, classes, types, etc.
   Instead, members are subdivided into three categories:
   - value members (defs, vals, vars, objects, packages) that result in a value
     (and possibly a side-effect) when they are accessed;
   - type members (traits, classes, abstract types, type aliases) that result
     in a type (and possibly a constructor) when they are accessed;
   - instance constructors for the class.
 - At the top of the members list is a field titled "inherits" that contains
   the linearization of the class's ancestors (see the Scala language
   specification §5.1.2). This is a list of all classes from which the current
   class can inherit members. Clicking on the ancestors selects which inherited
   members are listed. If all ancestors are grayed out, only locally defined or
   overridden members are listed.
 - Each package has its own page.

Wiki-like syntax in documentation source
----------------------------------------

Authors of documentation no longer have to use HTML tags in their comments.
Instead, Scaladoc supports a wiki-like syntax very similar to that used in Trac.
In general, Scaladoc authors should no longer use HTML tags in documentation as
Scaladoc may in the future also generate documentation in other formats than
HTML.

Wiki syntax is dependent of left-side alignment: the star marking the beginning
of a Scaladoc line marks the beginning of the left side for parsing purposes
(start-of-line markers are mandatory). Here is a small example of Scaladoc-
supported wiki syntax.

/** This is a paragraph
 *
 * This is another paragraph (note the empty line above) containing '''bold''',
 * ''italic'', `monospace`,
 * __underline__, ^superscript^, and ,,subscript,, words.
 *
 * {{{
 * Multi-line code can be inserted as a block and will be printed as monospace
 * text.
 * It isn't parsed as Scala, with keyword highlighting, but may be in the
 * future.
 * }}}
 *
 * In the near future, wiki syntax will also support bullet or number lists as
 * well as links to the www and to other pages inside the documentation. */

Compile-time error checking of documentation source
---------------------------------------------------

The Scaladoc comment parser will report invalid tags. Valid tags are:
 - @author (multiple allowed);
 - @see (multiple allowed);
 - @return (one allowed);
 - @throws <exception class> (one allowed per exception);
 - @param <param name> (one allowed per value parameter);
 - @tparam <param name> (one allowed per type parameter);
 - @version (one allowed);
 - @since (one allowed);
 - @todo (multiple allowed);
 - @deprecated (multiple allowed).

The Scaladoc comment parser will report invalid wiki syntax, such as unclosed
formatting ('''bold for example), unclosed code blocks, or missing start-of-line
markers.

Missing features
----------------

Scaladoc 2 is still in development. This is a list of missing features.

 - Documentation:
   - Inheritance chain of members (definition class, then all overrides) is
     printed.
   - Subclasses are printed.
   - Templates (classes, traits and objects) in types are links.
   - Each owner element (at the top of the page) is a link.
   - Documentation source at top of package objects is used by Scaladoc.
   - Function, Tuple and Product classes are not listed.
   - More comment tags are printed in the documentation (author, see, since,
     etc.).
   - There is a link to the source.

 - Wiki syntax:
   - Supports link tags.
   - Supports bullet or number lists.

 - HTML:
   - Pages works as expected in Internet Explorer 8 & 9 (possibly also 7,
     certainly not 6).
   - The right side of the page is more compact, with less padding and smaller
     text.
   - The filter tool for packages is easily recognizable for what it is, not
     just an empty, mysterious space.
   - There is a filter tool for members.
   - The filter tool has a better performance for large documentation.
   - Documentation for members is hidden by default and shown when clicking the
     signature.
   - Documentation for value and type parameters is shown when clicking the
     parameter name.




--
Daniel C. Sobral

Veni, vidi, veterni.

dubochet
Joined: 2008-06-30,
User offline. Last seen 1 year 36 weeks ago.
Re: Scaladoc 2

Hello Blair.

>> As of revision 19844, Scaladoc 2 replace the old Scaladoc in all trunk and 2.8
>> builds. Have a look at the trunk nightly Scaladoc.
>>
>> http://www.scala-lang.org/archives/downloads/distrib/files/nightly/docs/...
>
> Nice work.
>
> In the "inherits" section at the top I would like to see classes/traits be links the the documentation.

I'll add something like that, yes.

> Listing subclasses and subtraits that extend whatever you're looking at is also very useful when you're trying to decide which implementation of an interface to use. The list of subclasses and subtraits should not be limited just to to sealed traits/classes.

In the todo list: "Subclasses are printed"

https://lampsvn.epfl.ch/trac/scala/wiki/Scaladoc

> I find scrolling the left bar to find the section of classes takes too long. I like what GotApi did with their JavaDocs where you can expand or collapse packages and then click on the class you want:

I plan to do something like GotApi up to the level of classes (it's in the todo list). I don't think however that I'll list individual members in the left list: I fear that JavaScript filtering will become too costly for that many elements, even with an improved script.

Cheers,
Gilles.

dubochet
Joined: 2008-06-30,
User offline. Last seen 1 year 36 weeks ago.
Re: Scaladoc 2

Hello Kevin.

I am working directly agains trunk.

Cheers,
Gilles.

> For the sake of contributing bug fixes and enhancements...
> Are you working on this directly against svn, or do you have a git clone someplace?

dubochet
Joined: 2008-06-30,
User offline. Last seen 1 year 36 weeks ago.
Re: Scaladoc 2

>> The documentation isn't building on windows right now. It fails trying to create the file "::.html", which, for obvious reasons, it will never be able to.
> This has now become a blocker for me.

It's fixed in r19897. Note that building Scaladoc for the whole standard library requires a large amount of memory: I run it with 1.5 GB.

Cheers,
Gilles.

Chris Marshall
Joined: 2009-06-17,
User offline. Last seen 44 weeks 3 days ago.
RE: Scaladoc 2
> Wiki-like syntax in documentation source
> ----------------------------------------
>
> Authors of documentation no longer have to use HTML tags in their comments.
> Instead, Scaladoc supports a wiki-like syntax very similar to that used in Trac.
> In general, Scaladoc authors should no longer use HTML tags in documentation as
> Scaladoc may in the future also generate documentation in other formats than

I have to say that I completely disagree with this; it's completely the wrong way to go at the moment in my opinion. There are a gazillion Wikis out there with a gazillion markups; why would you choose one now? Is it an accepted standard? Like it or not, verbose it may be but HTML is standardized, most developers understand it and can parse it easily. When I'm reading the doc from within the source code (which I often do), I can't parse this markup because I don't know it.

Does every scala project out there need to change its scaladoc from HTML to markup? If so, we'll need to re-document everything just to migrate from 2.7->2.8! This just seems like madness to me.

On the other notes, given all your "todos", I think that the results are pretty good. A few pastel shades and rounded corners a la RoR/Web2.0 wouldn't go amiss though :-)


Add other email accounts to Hotmail in 3 easy steps. Find out how.
milessabin
Joined: 2008-08-11,
User offline. Last seen 33 weeks 3 days ago.
Re: Scaladoc 2

On Thu, Nov 26, 2009 at 3:09 PM, christopher marshall
wrote:
>> Wiki-like syntax in documentation source
>> ----------------------------------------
>>
>> Authors of documentation no longer have to use HTML tags in their
>> comments.
>> Instead, Scaladoc supports a wiki-like syntax very similar to that used in
>> Trac.
>> In general, Scaladoc authors should no longer use HTML tags in
>> documentation as
>> Scaladoc may in the future also generate documentation in other formats
>> than
>
> I have to say that I completely disagree with this; it's completely the
> wrong way to go at the moment in my opinion.

> Does every scala project out there need to change its scaladoc from HTML to
> markup? If so, we'll need to re-document everything just to migrate from
> 2.7->2.8! This just seems like madness to me.

I agree that this is the wrong direction to be going in. I would have
liked to see convergence with Javadoc: ideally we should be able to
produce integrated documentation for mixed Scala/Java projects and
that's looking to be an increasingly remote prospect.

Has anyone looked into supporting Scala via a Javadoc doclet?

Cheers,

Miles

odersky
Joined: 2008-07-29,
User offline. Last seen 45 weeks 6 days ago.
Re: Scaladoc 2

On Thu, Nov 26, 2009 at 4:20 PM, Miles Sabin wrote:
> On Thu, Nov 26, 2009 at 3:09 PM, christopher marshall
> wrote:
>>> Wiki-like syntax in documentation source
>>> ----------------------------------------
>>>
>>> Authors of documentation no longer have to use HTML tags in their
>>> comments.
>>> Instead, Scaladoc supports a wiki-like syntax very similar to that used in
>>> Trac.
>>> In general, Scaladoc authors should no longer use HTML tags in
>>> documentation as
>>> Scaladoc may in the future also generate documentation in other formats
>>> than
>>
>> I have to say that I completely disagree with this; it's completely the
>> wrong way to go at the moment in my opinion.
>
>
>> Does every scala project out there need to change its scaladoc from HTML to
>> markup? If so, we'll need to re-document everything just to migrate from
>> 2.7->2.8! This just seems like madness to me.
>
> I agree that this is the wrong direction to be going in. I would have
> liked to see convergence with Javadoc: ideally we should be able to
> produce integrated documentation for mixed Scala/Java projects and
> that's looking to be an increasingly remote prospect.
>
Note that wiki syntax is optional, not required. In browsing through
the existing scaladocs I have found a clear correspondance of html
tags and incorrectness in comments. The more tags the less correct the
comment was. The reason is clear: html tags make comments far less
legible in source code. So until all our program editors render html
inline, html comments will be painful to read and maintain, which
means that people won't do it. I personally would refuse categorically
typing out html tags. I am not the slave of my machine and I'd much
rather spend my time writing more and clearer docs than manually
tagging them. Maybe big enterprises can pay documenters to write all
these tags. We can't, so we have to make the experience of writing a
doc comment as painless as possible. For these reasons I believe wiki
syntax is a huge step forward!

Cheers

Mohamed Bana 2
Joined: 2009-10-21,
User offline. Last seen 42 years 45 weeks ago.
Re: Scaladoc 2
Was markdown considered?  http://johnmacfarlane.net/pandoc/README.html#pandocs-markdown-vsstandard-markdown has examples.
—Mohamed


On Thu, Nov 26, 2009 at 3:09 PM, christopher marshall <oxbow_lakes [at] hotmail [dot] com> wrote:
> Wiki-like syntax in documentation source
> ----------------------------------------
>
> Authors of documentation no longer have to use HTML tags in their comments.
> Instead, Scaladoc supports a wiki-like syntax very similar to that used in Trac.
> In general, Scaladoc authors should no longer use HTML tags in documentation as
> Scaladoc may in the future also generate documentation in other formats than

I have to say that I completely disagree with this; it's completely the wrong way to go at the moment in my opinion. There are a gazillion Wikis out there with a gazillion markups; why would you choose one now? Is it an accepted standard? Like it or not, verbose it may be but HTML is standardized, most developers understand it and can parse it easily. When I'm reading the doc from within the source code (which I often do), I can't parse this markup because I don't know it.

Does every scala project out there need to change its scaladoc from HTML to markup? If so, we'll need to re-document everything just to migrate from 2.7->2.8! This just seems like madness to me.

On the other notes, given all your "todos", I think that the results are pretty good. A few pastel shades and rounded corners a la RoR/Web2.0 wouldn't go amiss though :-)


Add other email accounts to Hotmail in 3 easy steps. Find out how.

Chris Marshall
Joined: 2009-06-17,
User offline. Last seen 44 weeks 3 days ago.
RE: Scaladoc 2
Ah, I didn't appreciate the optionality in the original email (obvious now, looking at it). IDEA 9 Community Edition is free and CTRL-Q pops up a rendered view of the documentation.

For what it's worth, I still think markup is a mistake - it just adds an extra layer of confusion: "you say tomato, I say potato" for the sake of it. I just don't see that the benefit warrants the cost in lost standardization. Just my opinion.


> Date: Thu, 26 Nov 2009 16:43:56 +0100
> Subject: Re: [scala-internals] Scaladoc 2
> From: martin [dot] odersky [at] epfl [dot] ch
> To: miles [at] milessabin [dot] com
> CC: oxbow_lakes [at] hotmail [dot] com; gilles [dot] dubochet [at] epfl [dot] ch; scala-internals [at] listes [dot] epfl [dot] ch
>
> On Thu, Nov 26, 2009 at 4:20 PM, Miles Sabin <miles [at] milessabin [dot] com> wrote:
> > On Thu, Nov 26, 2009 at 3:09 PM, christopher marshall
> > <oxbow_lakes [at] hotmail [dot] com> wrote:
> >>> Wiki-like syntax in documentation source
> >>> ----------------------------------------
> >>>
> >>> Authors of documentation no longer have to use HTML tags in their
> >>> comments.
> >>> Instead, Scaladoc supports a wiki-like syntax very similar to that used in
> >>> Trac.
> >>> In general, Scaladoc authors should no longer use HTML tags in
> >>> documentation as
> >>> Scaladoc may in the future also generate documentation in other formats
> >>> than
> >>
> >> I have to say that I completely disagree with this; it's completely the
> >> wrong way to go at the moment in my opinion.
> > <snip/>
> >
> >> Does every scala project out there need to change its scaladoc from HTML to
> >> markup? If so, we'll need to re-document everything just to migrate from
> >> 2.7->2.8! This just seems like madness to me.
> >
> > I agree that this is the wrong direction to be going in. I would have
> > liked to see convergence with Javadoc: ideally we should be able to
> > produce integrated documentation for mixed Scala/Java projects and
> > that's looking to be an increasingly remote prospect.
> >
> Note that wiki syntax is optional, not required. In browsing through
> the existing scaladocs I have found a clear correspondance of html
> tags and incorrectness in comments. The more tags the less correct the
> comment was. The reason is clear: html tags make comments far less
> legible in source code. So until all our program editors render html
> inline, html comments will be painful to read and maintain, which
> means that people won't do it. I personally would refuse categorically
> typing out html tags. I am not the slave of my machine and I'd much
> rather spend my time writing more and clearer docs than manually
> tagging them. Maybe big enterprises can pay documenters to write all
> these tags. We can't, so we have to make the experience of writing a
> doc comment as painless as possible. For these reasons I believe wiki
> syntax is a huge step forward!
>
> Cheers
>
> -- Martin
>
>
>
>
>
> > Has anyone looked into supporting Scala via a Javadoc doclet?
> >
>
>
>
> > Cheers,
> >
> >
> > Miles
> >
> > --
> > Miles Sabin
> > tel: +44 (0)7813 944 528
> > skype:  milessabin
> > http://www.chuusai.com/
> > http://twitter.com/milessabin
> >
> >

Have more than one Hotmail account? Link them together to easily access both.
milessabin
Joined: 2008-08-11,
User offline. Last seen 33 weeks 3 days ago.
Re: Scaladoc 2

On Thu, Nov 26, 2009 at 3:43 PM, martin odersky wrote:
> Note that wiki syntax is optional, not required. In browsing through
> the existing scaladocs I have found a clear correspondance of html
> tags and incorrectness in comments. The more tags the less correct the
> comment was. The reason is clear: html tags make comments far less
> legible in source code. So until all our program editors render html
> inline, html comments will be painful to read and maintain, which
> means that people won't do it. I personally would refuse categorically
> typing out html tags. I am not the slave of my machine and I'd much
> rather spend my time writing more and clearer docs than manually
> tagging them. Maybe big enterprises can pay documenters to write all
> these tags. We can't, so we have to make the experience of writing a
> doc comment as painless as possible. For these reasons I believe wiki
> syntax is a huge step forward!

I don't think that conficts with anything I said :-)

I'm pretty sure it's possible to put together a Javadoc doclet which
accepts wiki markup as well.

Cheers,

Miles

Blair Zajac
Joined: 2009-01-12,
User offline. Last seen 42 years 45 weeks ago.
Re: Scaladoc 2

On Nov 26, 2009, at 7:09 AM, christopher marshall wrote:

> > Wiki-like syntax in documentation source
> > ----------------------------------------
> >
> > Authors of documentation no longer have to use HTML tags in their comments.
> > Instead, Scaladoc supports a wiki-like syntax very similar to that used in Trac.
> > In general, Scaladoc authors should no longer use HTML tags in documentation as
> > Scaladoc may in the future also generate documentation in other formats than
>
> I have to say that I completely disagree with this; it's completely the wrong way to go at the moment in my opinion. There are a gazillion Wikis out there with a gazillion markups; why would you choose one now? Is it an accepted standard? Like it or not, verbose it may be but HTML is standardized, most developers understand it and can parse it easily. When I'm reading the doc from within the source code (which I often do), I can't parse this markup because I don't know it.

I think that's a little of an exaggeration. There's probably only three to choose from:

- mediawiki style
- trac style
- markdown style (used by stackoverflow and github)

None of them are exactly complicated.

Blair

Chris Marshall
Joined: 2009-06-17,
User offline. Last seen 44 weeks 3 days ago.
RE: Scaladoc 2

> I think that's a little of an exaggeration. There's probably only three to choose from:
>
> - mediawiki style
> - trac style
> - markdown style (used by stackoverflow and github)

Well, it *was* a little exaggeration. I know that Confluence is different from Markdown which is different from Mediawiki which is different from PHP bb (which is different from Trac?). That's at least 4.

> None of them are exactly complicated.

None of them are "The standard" either, which is why I don't see this adding value. It would be like building a compiler which assumes that all users will want to use Eclipse (admittedly not quite as bad as that)




Add other email accounts to Hotmail in 3 easy steps. Find out how.
Kevin Wright
Joined: 2009-06-09,
User offline. Last seen 49 weeks 3 days ago.
Re: Scaladoc 2
Thanks for the r19897 fixes :)It's good to see fast progress being made!

On Thu, Nov 26, 2009 at 4:56 PM, christopher marshall <oxbow_lakes [at] hotmail [dot] com> wrote:

> I think that's a little of an exaggeration. There's probably only three to choose from:
>
> - mediawiki style
> - trac style
> - markdown style (used by stackoverflow and github)

Well, it *was* a little exaggeration. I know that Confluence is different from Markdown which is different from Mediawiki which is different from PHP bb (which is different from Trac?). That's at least 4.

> None of them are exactly complicated.

None of them are "The standard" either, which is why I don't see this adding value. It would be like building a compiler which assumes that all users will want to use Eclipse (admittedly not quite as bad as that)




Add other email accounts to Hotmail in 3 easy steps. Find out how.

ijuma
Joined: 2008-08-20,
User offline. Last seen 22 weeks 2 days ago.
RE: Scaladoc 2

On Thu, 2009-11-26 at 16:56 +0000, christopher marshall wrote:
> None of them are "The standard" either, which is why I don't see this
> adding value. It would be like building a compiler which assumes that
> all users will want to use Eclipse (admittedly not quite as bad as
> that)

Not really. The Scala syntax is not a standard either. If the Scala team
can design the syntax for a programming language (which we take the time
to learn), they can also choose a good syntax for the documentation of
such programming language. The fact that it's based on an existing wiki
mark-up is a bonus.

Best,
Ismael

Chris Marshall
Joined: 2009-06-17,
User offline. Last seen 44 weeks 3 days ago.
RE: Scaladoc 2
Well, we'll have to agree to disagree. The markup with which to display text formatted for viewing on the internet is (I suspect) not what the scala dev team would see as being their core competency (or "edge", "usp", "differentiator" whatever) whereas the scala syntax is. To gain adoption, it's best that everything that doesn't absolutely have to be different should be familiar to people. It's also better that these non-core things should be as standardised as possible, for future-proofing and to ensure the minimum barrier to newcomers.

To my mind this has the hallmarks of change for change's sake: is the currrent HTML markup a big issue? I haven't seen *one single* complaint about it in the entire year I've been on this list.

It's not that I feel passionately about the Wiki thing; I just think it's a bad idea and hope I've presented my arguments.

Chris

> Subject: RE: [scala-internals] Scaladoc 2
> From: mlists [at] juma [dot] me [dot] uk
> To: oxbow_lakes [at] hotmail [dot] com
> CC: blair [at] orcaware [dot] com; gilles [dot] dubochet [at] epfl [dot] ch; scala-internals [at] listes [dot] epfl [dot] ch
> Date: Thu, 26 Nov 2009 17:12:52 +0000
>
> On Thu, 2009-11-26 at 16:56 +0000, christopher marshall wrote:
> > None of them are "The standard" either, which is why I don't see this
> > adding value. It would be like building a compiler which assumes that
> > all users will want to use Eclipse (admittedly not quite as bad as
> > that)
>
> Not really. The Scala syntax is not a standard either. If the Scala team
> can design the syntax for a programming language (which we take the time
> to learn), they can also choose a good syntax for the documentation of
> such programming language. The fact that it's based on an existing wiki
> mark-up is a bonus.
>
> Best,
> Ismael
>

New! Receive and respond to mail from other email accounts from within Hotmail Find out how.
ijuma
Joined: 2008-08-20,
User offline. Last seen 22 weeks 2 days ago.
RE: Scaladoc 2

On Thu, 2009-11-26 at 17:30 +0000, christopher marshall wrote:
> Well, we'll have to agree to disagree. The markup with which to
> display text formatted for viewing on the internet is (I suspect) not
> what the scala dev team would see as being their core competency (or
> "edge", "usp", "differentiator" whatever) whereas the scala syntax is.

Scaladoc is not just about displaying on the internet. It's also about
reading it directly in the source and making it easily editable
(although the importance of each is not the same). Personally, I read it
much more often along with the source than otherwise.

> To gain adoption, it's best that everything that doesn't absolutely
> have to be different should be familiar to people. It's also better
> that these non-core things should be as standardised as possible, for
> future-proofing and to ensure the minimum barrier to newcomers.

I don't agree with the emphasis. Scala should not change things for the
sake of change and compatibility is important, sure. However, if there
is an opportunity to improve something with little downside, it should
be done.

> To my mind this has the hallmarks of change for change's sake: is the
> currrent HTML markup a big issue? I haven't seen *one single*
> complaint about it in the entire year I've been on this list.

Well, there have been complaints about scaladoc's sparsity and Martin
has just said "I personally would refuse categorically
typing out html tags. I am not the slave of my machine and I'd much
rather spend my time writing more and clearer docs than manually
tagging them". That seems like a complaint to me.

Whether a nicer mark-up is enough for committers and contributors to
improve the scaladoc is an open question, of course.

Best,
Ismael

dcsobral
Joined: 2009-04-23,
User offline. Last seen 38 weeks 5 days ago.
Re: Scaladoc 2
I think leaving standard is bad, but I just have to side with wiki against HTML here. HTML is just plain difficult to edit by hand, and when I'm writing code, by hand is what I have available -- it doesn't break the flow.   That said, there are really few things that are relevant for API docs. Foremost, easy insertion of source code, both as samples and as in-line snippets. Stack Overflow does it nicely in this respect, but identation won't cut it because we put the "*" at the beginning of the line.   Next, tables, and items.   Finally, internal and external links. The wiki used by Rosetta is really nice in this respect.   Most of the other stuff is plain unnecessary.
On Thu, Nov 26, 2009 at 3:49 PM, Ismael Juma <mlists [at] juma [dot] me [dot] uk> wrote:
On Thu, 2009-11-26 at 17:30 +0000, christopher marshall wrote:
> Well, we'll have to agree to disagree. The markup with which to
> display text formatted for viewing on the internet is (I suspect) not
> what the scala dev team would see as being their core competency (or
> "edge", "usp", "differentiator" whatever) whereas the scala syntax is.

Scaladoc is not just about displaying on the internet. It's also about
reading it directly in the source and making it easily editable
(although the importance of each is not the same). Personally, I read it
much more often along with the source than otherwise.

>  To gain adoption, it's best that everything that doesn't absolutely
> have to be different should be familiar to people. It's also better
> that these non-core things should be as standardised as possible, for
> future-proofing and to ensure the minimum barrier to newcomers.

I don't agree with the emphasis. Scala should not change things for the
sake of change and compatibility is important, sure. However, if there
is an opportunity to improve something with little downside, it should
be done.

> To my mind this has the hallmarks of change for change's sake: is the
> currrent HTML markup a big issue? I haven't seen *one single*
> complaint about it in the entire year I've been on this list.

Well, there have been complaints about scaladoc's sparsity and Martin
has just said "I personally would refuse categorically
typing out html tags. I am not the slave of my machine and I'd much
rather spend my time writing more and clearer docs than manually
tagging them". That seems like a complaint to me.

Whether a nicer mark-up is enough for committers and contributors to
improve the scaladoc is an open question, of course.

Best,
Ismael




--
Daniel C. Sobral

Veni, vidi, veterni.
Tony Morris 2
Joined: 2009-03-20,
User offline. Last seen 42 years 45 weeks ago.
Re: Scaladoc 2

Are there plans to properly support unicode identifiers? Scaladoc for
2.7 seems to handle it fine, however:

$ echo "object T { val ⊛ = 7 }" > t.scala &&
~/scala-2.8.0.r19853-b20091125020156/bin/scaladoc t.scala && firefox
index.html
uni

Gilles Dubochet wrote:
> As of revision 19844, Scaladoc 2 replace the old Scaladoc in all trunk and 2.8
> builds. Have a look at the trunk nightly Scaladoc.
>
> http://www.scala-lang.org/archives/downloads/distrib/files/nightly/docs/...
>
> Scaladoc 2 is a major update to Scaladoc by Manohar Jonnalagedda and Gilles
> Dubochet. It is based on the original Scaladoc (Sean McDirmid, Geoffrey
> Washburn, Vincent Cremet and Stéphane Michleoud) as well as on vScaladoc (David
> Bernard).
>
> Beside usual bug reports, I am interested in feedback concerning the usability
> of Scaladoc. Please, send in use-cases of what you were searching for, and why
> you did or did not find it easily in Scaladoc. General feedback about the look
> and feel of Scaladoc is also wanted.
>
> A new look and feel for documentation pages
> -------------------------------------------
>
> The left bar of the documentation page, listing packages and top-level objects,
> is simpler. There are no separate lists for packages, classes and objects.
> Instead, there is a single list contains packages and their nested classes and
> objects. Classes and their companion objects are a single entry in the list. A
> text box at the top of the list (look for an empty blank space) allows to
> interactively filter the list by entering a package name, class name, or a part
> thereof.
>
> The right side of the page, with the documentation for a single class, trait,
> object or package, is organized differently. Most notably:
> - All members, inherited or locally defined are listed as actual members (not
> just links to the definition in the super-class), with their types as seen
> from the current class.
> - There is no more distinction between vals, defs, classes, types, etc.
> Instead, members are subdivided into three categories:
> - value members (defs, vals, vars, objects, packages) that result in a value
> (and possibly a side-effect) when they are accessed;
> - type members (traits, classes, abstract types, type aliases) that result
> in a type (and possibly a constructor) when they are accessed;
> - instance constructors for the class.
> - At the top of the members list is a field titled "inherits" that contains
> the linearization of the class's ancestors (see the Scala language
> specification §5.1.2). This is a list of all classes from which the current
> class can inherit members. Clicking on the ancestors selects which inherited
> members are listed. If all ancestors are grayed out, only locally defined or
> overridden members are listed.
> - Each package has its own page.
>
> Wiki-like syntax in documentation source
> ----------------------------------------
>
> Authors of documentation no longer have to use HTML tags in their comments.
> Instead, Scaladoc supports a wiki-like syntax very similar to that used in Trac.
> In general, Scaladoc authors should no longer use HTML tags in documentation as
> Scaladoc may in the future also generate documentation in other formats than
> HTML.
>
> Wiki syntax is dependent of left-side alignment: the star marking the beginning
> of a Scaladoc line marks the beginning of the left side for parsing purposes
> (start-of-line markers are mandatory). Here is a small example of Scaladoc-
> supported wiki syntax.
>
> /** This is a paragraph
> *
> * This is another paragraph (note the empty line above) containing '''bold''',
> * ''italic'', `monospace`,
> * __underline__, ^superscript^, and ,,subscript,, words.
> *
> * {{{
> * Multi-line code can be inserted as a block and will be printed as monospace
> * text.
> * It isn't parsed as Scala, with keyword highlighting, but may be in the
> * future.
> * }}}
> *
> * In the near future, wiki syntax will also support bullet or number lists as
> * well as links to the www and to other pages inside the documentation. */
>
> Compile-time error checking of documentation source
> ---------------------------------------------------
>
> The Scaladoc comment parser will report invalid tags. Valid tags are:
> - @author (multiple allowed);
> - @see (multiple allowed);
> - @return (one allowed);
> - @throws (one allowed per exception);
> - @param (one allowed per value parameter);
> - @tparam (one allowed per type parameter);
> - @version (one allowed);
> - @since (one allowed);
> - @todo (multiple allowed);
> - @deprecated (multiple allowed).
>
> The Scaladoc comment parser will report invalid wiki syntax, such as unclosed
> formatting ('''bold for example), unclosed code blocks, or missing start-of-line
> markers.
>
> Missing features
> ----------------
>
> Scaladoc 2 is still in development. This is a list of missing features.
>
> - Documentation:
> - Inheritance chain of members (definition class, then all overrides) is
> printed.
> - Subclasses are printed.
> - Templates (classes, traits and objects) in types are links.
> - Each owner element (at the top of the page) is a link.
> - Documentation source at top of package objects is used by Scaladoc.
> - Function, Tuple and Product classes are not listed.
> - More comment tags are printed in the documentation (author, see, since,
> etc.).
> - There is a link to the source.
>
> - Wiki syntax:
> - Supports link tags.
> - Supports bullet or number lists.
>
> - HTML:
> - Pages works as expected in Internet Explorer 8 & 9 (possibly also 7,
> certainly not 6).
> - The right side of the page is more compact, with less padding and smaller
> text.
> - The filter tool for packages is easily recognizable for what it is, not
> just an empty, mysterious space.
> - There is a filter tool for members.
> - The filter tool has a better performance for large documentation.
> - Documentation for members is hidden by default and shown when clicking the
> signature.
> - Documentation for value and type parameters is shown when clicking the
> parameter name.
>
>

Vladimir Kirichenko
Joined: 2009-02-19,
User offline. Last seen 42 years 45 weeks ago.
Re: Scaladoc 2

> The fact that it's based on an existing wiki
> mark-up is a bonus.

As for me it would be better to support structured text aka plaintext tags:

*bold*
/italic/
_underlined_
|code|

which is part of every mail client.

PS: Tnx, Ismael

Copyright © 2012 École Polytechnique Fédérale de Lausanne (EPFL), Lausanne, Switzerland