Top API Wishes:
Proposed focus of the October 15 docspree:
- More examples, everywhere! It would be nice to include simple examples of many methods, especially on collections, that one could copy/paste into the REPL.
Classes/traits/objects which would benefit most from examples:
- scala.collection.mutable.Array: fill, tabulate methods for constructing arrays.
- scala.Either: let's follow the example of scala.Option (nightly)
- Overview documentation for packages (regardless of whether or not the package has a package object. We'll find a way to incorporate it, but we need the content first!)
Biggest Scaladoc Wishes:
(For those of you who would rather work on the tool than API documentation)
- Documentation to packages, when there's no package object. We don't want to have to create empty package objects.
- Make it possible to link to members.
If you have a topic where you'd like to see more documentation add it to this list!
Claim a topic to work on by writing your name after the bullet point.
- Scala Swing. Pretty much everything needs documentation and even more important actual code examples and use-cases!
- Always check the classes' companion objects, too. Often missing documentation shows up by accident there. Moving documentation to the right place is an immediate improvement!
- Many collections deserve a far better introduction, including performance characteristics. Insight into many of Scala's collections exist at Overview of the Collections API (including performance characteristics!!), but none of this lives in the API. Java's java.util.HashMapis an excellent example of what collections documentation should strive to be like. Collections to look at include:
- ...amongst many, many, many others...
- The usage of traits like scala.collection.GenSeq should be explained in the introduction, along with usage examples. Java's interface java.lang.Runnable is an excellent example to follow.
- Maybe include a link to the "What's new in 2.8" guide in scala.actors.Actor?
- It would be nice if the scala.util.parsing.json.JSON object had an example in the introduction.
- Java's java.util.String is a friendly and example-rich doc page worth looking at for inspiration, in general.
Status of Individuals: