Documentation: Suggested Improvements?

Hi all, 
I'll be responsible for the docspree event at Scalathon this Friday. About thirty Scalathon attendees will getting together to improve/contribute to the documentation present in the official Scala API, and we'll be merging improvements as they are produced.
I've read many posts from the past few weeks which have cited different areas to be improved, but would like to open up the floor (duplicated on scala-user) to you guys to collect more suggestions on what you think needs to be improved. 
This Friday, we'll work en masse on your suggestions, and you should be able to see them shortly after, in the scaladoc nightly build. 
So- where can we begin to improve documentation? Is there some specific part of the API that threw you for a loop, and which you would like to see improved?


Cheers, Heather

What's the scope of this event?
Is it simply about improving documentation on APis in the standard library, or will you also be considering improvements to the mechanics of Scaladoc?


On 14 July 2011 00:11, Miller Heather <heather.miller@epfl.ch> wrote:

Hi all, 
I'll be responsible for the docspree event at Scalathon this Friday. About thirty Scalathon attendees will getting together to improve/contribute to the documentation present in the official Scala API, and we'll be merging improvements as they are produced.
I've read many posts from the past few weeks which have cited different areas to be improved, but would like to open up the floor (duplicated on scala-user) to you guys to collect more suggestions on what you think needs to be improved. 
This Friday, we'll work en masse on your suggestions, and you should be able to see them shortly after, in the scaladoc nightly build. 
So- where can we begin to improve documentation? Is there some specific part of the API that threw you for a loop, and which you would like to see improved?


Cheers, Heather

--
Kevin Wright

gtalk / msn : kev.lee.wright@gmail.comgoogle+: http://gplus.to/thecoda
kev.lee.wright@gmail.commail: kevin.wright@scalatechnology.com
vibe / skype: kev.lee.wright quora: http://www.quora.com/Kevin-Wright
twitter: @thecoda

"My point today is that, if we wish to count lines of code, we should not regard them as "lines produced" but as "lines spent": the current conventional wisdom is so foolish as to book that count on the wrong side of the ledger" ~ Dijkstra

I don't know if this covers the subject:

I made in this thread some suggestions about including performance
characteristics of methods (@bigo ?) in the documentation in
particularly collection methods and other things like order
preservation and other interesting and useful selection criteria:
see:
http://www.scala-lang.org/node/10084#comment-43412

Another suggestion is more usage examples, some features are not
documented and thus awkward compatibility breaking code duplication
solutions are invented:
For Enumeration.scala for example Sean's example as second usage
example if you want to extend Value to add attributes:
see:
http://www.scala-lang.org/node/10031?page=1#comment-43299

In short: more integration between documentation and source code to
keep documentation up to date and to make it convenient to do that,
the documentation is in fragments everywhere and is therefore not
updated.

Hi,

> The docspree is just on documenting the standard library (and the
> compiler?). However, Sat/Sun will have efforts both on API documentation
> (led by Heather), and the Scaladoc tool itself (led by Pedro)
>>> So- where can we begin to improve documentation? Is there some specific
>>> part of the API that threw you for a loop, and which you would like to see
>>> improved?

I would have five things in mind:

- Documentation of the "base" classes, e. g. those which are used
everywhere, like Double. Especially those near the top in ScalaDoc.
(It really doesn't make a good first impression if someone interested
in Scala sees that most of the basic things are not documented.) I
have started with scala.Boolean:
[https://github.com/scala/scala/pull/25 ,
https://issues.scala-lang.org/browse/SI-4468]

- Some custom "Welcome" or "Landing page" which explains what
ScalaDoc is, how it can be used and explains which other resources are
available.
This should replace the current starting page "root package" which is
shown when someone browses to ScalaDoc without any "bookmark".

- Documentation possibilities for type aliases (like String):
Either being able to document it despite the fact that it is some Java
class (or at least make it appear in the panel on the left and jump
directly to JavaDoc). [1]

- Configurable prefixes to point to existing third party documentation:
I imagine supplying some config file to the scaladoc tool, which
basically maps package names to URLs. E. g. I can specify that every
class/package starting with java/javax/sun/... should link to
http://download.java.net/jdk7/docs/api/ (instead of not linking
anywhere at all).

- It would be nice to get "Show attributes like "final" or
"abstract" in front of the class signature in ScalaDoc"
[https://github.com/scala/scala/pull/26
https://issues.scala-lang.org/browse/SI-4451] into a state where
everyone is happy with it, from both documentation- and
design-perspective and commit it.

I think those things could make a big difference in usability,
especially for new users.

Thanks and bye!

Simon

Sorry, forgot the footnote:

[1] We already have something slightly comparable with scala-aux
(which contains Any, AnyRef, Null, Nothing for "bootstrapping and
documentation purposes").

> - Documentation possibilities for type aliases (like String):
> Either being able to document it despite the fact that it is some Java
> class (or at least make it appear in the panel on the left and jump
> directly to JavaDoc). [1]

Two things that could be helpful.

* Include types and members inherited from Java such as java.lang.String
* Just as you can filter inherited methods, also include methods
"inherited" by implicit conversions.

These two are more of a tooling evolution though.

On the documentation end I think the first thing to focus on is the
collection API. Loads of examples and explanations in each type. Lots
of links and cross references to other parts of the API so it's easy
to find what one _should_ be looking for. Imagine a random googler
landing on something like GenMap looking for how to create maps.
Something should direct him/her to the correct (idiomatic) factories
and and constructors to use. Taking care to point towards issues such
as mutable vs immutable maps and so on.

Links should also point from the API-docs to guide-like documentation
providing tutorials. Think
http://download.oracle.com/javase/tutorial/collections/index.html

BR,
John

On Thu, Jul 14, 2011 at 1:11 AM, Miller Heather wrote:
> Hi all,
> I'll be responsible for the docspree event at Scalathon this Friday. About
> thirty Scalathon attendees will getting together to improve/contribute to
> the documentation present in the official Scala API, and we'll be merging
> improvements as they are produced.
> I've read many posts from the past few weeks which have cited different
> areas to be improved, but would like to open up the floor (duplicated on
> scala-user) to you guys to collect more suggestions on what you think needs
> to be improved.
> This Friday, we'll work en masse on your suggestions, and you should be able
> to see them shortly after, in the scaladoc nightly build.
> So- where can we begin to improve documentation? Is there some specific part
> of the API that threw you for a loop, and which you would like to see
> improved?
>
>
> Cheers,
> Heather

On Thu, Jul 14, 2011 at 15:09, John Nilsson wrote:
> Two things that could be helpful.
>
> * Include types and members inherited from Java such as java.lang.String
> * Just as you can filter inherited methods, also include methods
> "inherited" by implicit conversions.

Actually, I think any class should have list of classes to which it
can be implicitly converted, and maybe the link of where that
conversion is present. In fact, classes that are not otherwise defined
could have a scaladoc generated for them just listing this, which
would help third party libraries such as Scalaz or Scalacheck.

For example, the class Int could have:

Implicitly convertable to (by): RichInt (Predef.intWrapper)

And the Scaladoc for the standard library could have an entry for
java.lang.String without anything but:

Implicitly convertable to (by): StringOps (Predef.augmentString),
WrappedString (Predef.wrapString)

Anyway, just a thought.