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

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

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

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