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

Fwd: New Scala doc comment interface

4 replies
odersky
Joined: 2008-07-29,
User offline. Last seen 45 weeks 6 days ago.

---------- Forwarded message ----------
From: martin odersky
Date: Mon, Dec 7, 2009 at 7:48 PM
Subject: New Scala doc comment interface
To: Ilya Sergey , Alexander
, Caoyuan ,
Miles Sabin , Gilles Dubochet

Cc: scala-internalsl [at] epfl [dot] ch

Hi all,

Scala 2.8 will get a new format for doc comments. I'm sending this
mail to you now so that you know what goes on and that you can
hopefully adapt IDEs to the new format.

There are three main differences:

1.  Doc comments now support a wiki like syntax similar to trak
2.  They permit variables that can be redefined in subclasses.
3.  They permit use cases where a method can be presented with an
alternate, simplified type.

The changes have become necessary to do a good job documenting
libraries with rich types and inheritance relationships such as scala
collections.

To get a feeling for how the new doc comments look, have a look at
classes TraversableLike, IterableLike, SeqLike and List in the
scala.collections. I am about to upgrade the documentation of the
other classes accordingly.

New doc comments are supported by the class ast/DocComments in the
Scala compiler. The old interface, consisting of hashmaps `comments`
and `commentOffsets` in class Global is gone. Instead there are now
the following new members of DocComments (which gets mixed into
SymbolTable, so everything is again available by selecting from
Global):

 /** The raw doc comment of symbol `sym`, as it appears in the source
text, "" if missing.
  *  If a symbol does not have a doc comment but some overridden
version of it does,
  *  the doc comment of the overridden version is copied instead.
  *
  *  @param sym  the symbol for which doc comment is returned
  */
 def rawDocComment(sym: Symbol): String

 /** The doc comment of symbol `sym` after variable expansion, or ""
if missing.
  *  @param sym  the symbol for which doc comment is returned
  *  @param site the class for which doc comments are generated
  */
 def expandedDocComment(sym: Symbol, site: Symbol): String =
   getDocComment(sym) map (_.expanded(site)) getOrElse ""

   /** The position of the doc comment of symbol `sym`, or NoPosition
if missing */
 def docCommentPos(sym: Symbol): Position

 /** The list of use cases of doc comment of symbol `sym` seen as a
member of class
  *  `site`. Each use case consists of a synthetic symbol (which is
entered nowhere else),
  *  and an expanded doc comment string.
  */
 def useCases(sym: Symbol, site: Symbol): List[(Symbol, String)]

The idea is that where possible, IDEs should show use cases of a
symbol before the symbol itself.
A use case shows a simplified view of a method's type, which is easier
to understand than the full method type.
So to be effective, use cases should be presented before the user gets
to see the full type.

None of these methods does wiki syntax expansion, but you can get a
fully expanded version in JavaDoc format, using the following method:

 /** Return the javadoc format of doc comment string `s`, including
wiki expansion
  */
 def toJavaDoc(s: String): String

Comments very welcome!

Cheers

Ricky Clarkson
Joined: 2008-12-19,
User offline. Last seen 3 years 2 weeks ago.
Re: Fwd: New Scala doc comment interface

I really like the use cases idea, and hope that can help users to deal
with more interesting type signatures at their leisure, instead of
when they first hit Scala.

2009/12/7 martin odersky :
> ---------- Forwarded message ----------
> From: martin odersky
> Date: Mon, Dec 7, 2009 at 7:48 PM
> Subject: New Scala doc comment interface
> To: Ilya Sergey , Alexander
> , Caoyuan ,
> Miles Sabin , Gilles Dubochet
>
> Cc: scala-internalsl [at] epfl [dot] ch
>
>
> Hi all,
>
> Scala 2.8 will get a new format for doc comments. I'm sending this
> mail to you now so that you know what goes on and that you can
> hopefully adapt IDEs to the new format.
>
> There are three main differences:
>
> 1.  Doc comments now support a wiki like syntax similar to trak
> 2.  They permit variables that can be redefined in subclasses.
> 3.  They permit use cases where a method can be presented with an
> alternate, simplified type.
>
> The changes have become necessary to do a good job documenting
> libraries with rich types and inheritance relationships such as scala
> collections.
>
> To get a feeling for how the new doc comments look, have a look at
> classes TraversableLike, IterableLike, SeqLike and List in the
> scala.collections. I am about to upgrade the documentation of the
> other classes accordingly.
>
> New doc comments are supported by the class ast/DocComments in the
> Scala compiler. The old interface, consisting of hashmaps `comments`
> and `commentOffsets` in class Global is gone. Instead there are now
> the following new members of DocComments (which gets mixed into
> SymbolTable, so everything is again available by selecting from
> Global):
>
>  /** The raw doc comment of symbol `sym`, as it appears in the source
> text, "" if missing.
>   *  If a symbol does not have a doc comment but some overridden
> version of it does,
>   *  the doc comment of the overridden version is copied instead.
>   *
>   *  @param sym  the symbol for which doc comment is returned
>   */
>  def rawDocComment(sym: Symbol): String
>
>  /** The doc comment of symbol `sym` after variable expansion, or ""
> if missing.
>   *  @param sym  the symbol for which doc comment is returned
>   *  @param site the class for which doc comments are generated
>   */
>  def expandedDocComment(sym: Symbol, site: Symbol): String =
>    getDocComment(sym) map (_.expanded(site)) getOrElse ""
>
>    /** The position of the doc comment of symbol `sym`, or NoPosition
> if missing */
>  def docCommentPos(sym: Symbol): Position
>
>  /** The list of use cases of doc comment of symbol `sym` seen as a
> member of class
>   *  `site`. Each use case consists of a synthetic symbol (which is
> entered nowhere else),
>   *  and an expanded doc comment string.
>   */
>  def useCases(sym: Symbol, site: Symbol): List[(Symbol, String)]
>
> The idea is that where possible, IDEs should show use cases of a
> symbol before the symbol itself.
> A use case shows a simplified view of a method's type, which is easier
> to understand than the full method type.
> So to be effective, use cases should be presented before the user gets
> to see the full type.
>
> None of these methods does wiki syntax expansion, but you can get a
> fully expanded version in JavaDoc format, using the following method:
>
>  /** Return the javadoc format of doc comment string `s`, including
> wiki expansion
>   */
>  def toJavaDoc(s: String): String
>
> Comments very welcome!
>
> Cheers
>
>  -- Martin
>

Tony Morris 2
Joined: 2009-03-20,
User offline. Last seen 42 years 45 weeks ago.
Re: Fwd: New Scala doc comment interface

> 3. They permit use cases where a method can be presented with an
> alternate, simplified type.
>
>
Awesome.

Randall R Schulz
Joined: 2008-12-16,
User offline. Last seen 1 year 29 weeks ago.
Re: Fwd: New Scala doc comment interface

On Monday December 7 2009, martin odersky wrote:
> ...
>
> Scala 2.8 will get a new format for doc comments. ...
>
> There are three main differences:
>
> ...
> 3.  They permit use cases where a method can be presented with an
> alternate, simplified type.

Is this a response to the "suicide note" thread [1] on StackOverflow?

[1] 

> ...
>
> Cheers
>
>  -- Martin

Randall Schulz

odersky
Joined: 2008-07-29,
User offline. Last seen 45 weeks 6 days ago.
Re: Fwd: New Scala doc comment interface

On Tue, Dec 8, 2009 at 12:00 AM, Randall R Schulz wrote:
> On Monday December 7 2009, martin odersky wrote:
>> ...
>>
>> Scala 2.8 will get a new format for doc comments. ...
>>
>> There are three main differences:
>>
>> ...
>> 3.  They permit use cases where a method can be presented with an
>> alternate, simplified type.
>
> Is this a response to the "suicide note" thread [1] on StackOverflow?
>
>
> [1] 
>
Yes, indeed. I knew we had to do something like this for a while, but
the discussion on StackOverflow underlined the urgency of it.

Cheers

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