Contribute to Scaladoc 2

I asked a while back about actually contributing ScalaDoc (as opposed to contributing to ScalaDoc). I think even pretty basic and obvious methods should have examples of their usage, including "extended" examples for likely use-cases.

For example, on TraversableLike.map I would give examples showing how List.map results in a List whereas Set.map results in a Set. I would then go on to an example showing how to use breakOut to convert a collection like a Set into something like a Map.

Some of this stuff might well be logically unnecessary but I think is of great practical value and I would like to contribute.

Chris

> From: gilles.dubochet@epfl.ch
> Subject: [scala-internals] Contribute to Scaladoc 2
> Date: Mon, 18 Jan 2010 15:48:05 +0100
> To: scala-internals@listes.epfl.ch
>
> Dear Scala users & developers.
>
>
> Do you want to help making Scala better? Why not contribute to Scaladoc? It is useful, fun, and (relatively) easy. Find out why (and then, how to contribute):
>
> https://lampsvn.epfl.ch/trac/scala/wiki/Scaladoc/Contribute
>
>
> To help you contribute, I have written a description of Scaladoc's design:
>
> https://lampsvn.epfl.ch/trac/scala/wiki/Scaladoc/Design
>
>
> You can have a look at proposed changes (i.e. ideas of what you could contribute), but other contributions are also welcome:
>
> https://lampsvn.epfl.ch/trac/scala/wiki/Scaladoc/Todo
>
>
> The Scaladoc mini-site for developers links to all relevant resources:
>
> https://lampsvn.epfl.ch/trac/scala/wiki/Scaladoc
>
>
> Don't hesitate to contact me if you have any questions.
>
> Cheers,
> Gilles.

Do you want a Hotmail account? Sign-up now - Free

Hello Christopher.

> I asked a while back about actually contributing ScalaDoc (as opposed to contributing to ScalaDoc). I think even pretty basic and obvious methods should have examples of their usage, including "extended" examples for likely use-cases.

You are absolutely right: there is lots that can be improved in Scala's documentation. By all means, your contributions to the documentation are very welcome.

I agree that adding usage examples (let's not call them use cases as this now has a different meaning in Scaladoc) can be extremely useful, particularly for methods like "map" that ex-Java users may find difficult to grasp at first.

I forward you a message that Donna had sent to the Scala mailing list a while back, which may be of interest to those wanting to contribute to Scala's documentation:

> I've developed a tool that will take new scaladoc comments as an XML input and merge the changes back into the source. This way, anyone can submit scaladoc as a patch and then it can be added to the sources by anyone with commit priviledges.
>
> Here is an example input file:
>
>
>
> class
> scala/io/BufferedSource.scala
> scala.io.BufferedSource
> new scaladoc comment for BufferedSource
> Next line
>
>
>
> method
> scala/collection/Iterator.scala
> scala.collection.Iterator.copyToArray(Array[B], Int, Int)
> new scaladoc comment for copyToArray(Array[B], Int, Int)
>
>
>
> An entry has the following attributes:
> type: one of "class" "method" or "object"
> filename: use the file path given in the generated scaladoc
> identifier: fully qualified name of the identifier. For the case of overloaded methods, the type of each argument should also be given (otherwise an ambiguous error is reported by the tool).
> newcomment: a new comment string. This is automatically formatted as a scaladoc comment (i.e., adding the /*, */). Long lines will be wrapped by the tool, but line breaks within the comment are respected.
>
> For now, you will have to manually create the XML file, but it would be great if someone could write a wiki that would allow anyone to edit the scaladoc, along with a way of exporting the wiki to the XML file. Any volunteers?

If you need any additional information on how to submit comment patches using Donna's XML format, let me or Donna know.

Cheers,
Gilles.