Which core classes need the most doc improvements?

My very slow quest to improve the core library scaladoc is off to a good start.  I was planning to just go through each class, starting in scala._ improving things as I could.  However, not all classes are created equal and some might need more attention as far as documentation goes than others.
Can anyone point out some classes in the core library that need particular documentation improvements or where the docs are particularly wrong or confusing?  Or, put another way, which core classes were the most difficult to understand the first time you needed to use them?
Thanks,
Dave

---
My Blog: http://www.naildrivin5.com/blog
Scala Tour for Java Developers: http://www.naildrivin5.com/scalatour
Fork me on Github: http://davetron5000.github.com

Parser combinators?

On Mon, Aug 16, 2010 at 2:29 PM, David Copeland <davec@naildrivin5.com> wrote:

My very slow quest to improve the core library scaladoc is off to a good start.  I was planning to just go through each class, starting in scala._ improving things as I could.  However, not all classes are created equal and some might need more attention as far as documentation goes than others.
Can anyone point out some classes in the core library that need particular documentation improvements or where the docs are particularly wrong or confusing?  Or, put another way, which core classes were the most difficult to understand the first time you needed to use them?
Thanks,
Dave

---
My Blog: http://www.naildrivin5.com/blog
Scala Tour for Java Developers: http://www.naildrivin5.com/scalatour
Fork me on Github: http://davetron5000.github.com

I think XML could use some love too, particularly in the minor classes.

On Tue, Aug 17, 2010 at 4:58 PM, Naftoli Gugenheim <naftoligug@gmail.com> wrote:

Parser combinators?

On Mon, Aug 16, 2010 at 2:29 PM, David Copeland <davec@naildrivin5.com> wrote:

My very slow quest to improve the core library scaladoc is off to a good start.  I was planning to just go through each class, starting in scala._ improving things as I could.  However, not all classes are created equal and some might need more attention as far as documentation goes than others.
Can anyone point out some classes in the core library that need particular documentation improvements or where the docs are particularly wrong or confusing?  Or, put another way, which core classes were the most difficult to understand the first time you needed to use them?
Thanks,
Dave

---
My Blog: http://www.naildrivin5.com/blog
Scala Tour for Java Developers: http://www.naildrivin5.com/scalatour
Fork me on Github: http://davetron5000.github.com

--
Daniel C. Sobral

I travel to the future all the time.

I also vote for XML.

On Tue, Aug 17, 2010 at 6:22 PM, Daniel Sobral <dcsobral@gmail.com> wrote:

I think XML could use some love too, particularly in the minor classes.

On Tue, Aug 17, 2010 at 4:58 PM, Naftoli Gugenheim <naftoligug@gmail.com> wrote:

Parser combinators?

On Mon, Aug 16, 2010 at 2:29 PM, David Copeland <davec@naildrivin5.com> wrote:

My very slow quest to improve the core library scaladoc is off to a good start.  I was planning to just go through each class, starting in scala._ improving things as I could.  However, not all classes are created equal and some might need more attention as far as documentation goes than others.
Can anyone point out some classes in the core library that need particular documentation improvements or where the docs are particularly wrong or confusing?  Or, put another way, which core classes were the most difficult to understand the first time you needed to use them?
Thanks,
Dave

---
My Blog: http://www.naildrivin5.com/blog
Scala Tour for Java Developers: http://www.naildrivin5.com/scalatour
Fork me on Github: http://davetron5000.github.com

--
Daniel C. Sobral

I travel to the future all the time.

--
"You question the worthiness of my Code? I should kill you where you stand!"

Dave,

Tangentially off topic:

If you are doing this using Vim, may I suggest using
scalacommenter.vim
http://www.vim.org/scripts/script.php?script_id=3047
which might help with the formatting and @ tag generation parts of
a scaladoc comment.
Also, seeing that you are actually creating/editing some of Scala's
core library scaladocs, if you have any usage or formatting
suggestions I can add to the tool to make it more useful
I would be much appreciative.
For instance, which tags should be supported? What should
the order of the tags be? In a javadoc comment, the text does
not start on the the first line, "/**", but it seems that
in the Scala libraries the scaladoc comment text does start on
the first line ... should that be the default behavior? Etc. etc.

Thanks.

Richard

On 08/16/2010 11:29 AM, David Copeland wrote:
> My very slow quest to improve the core library scaladoc is off to a good
> start. I was planning to just go through each class, starting in
> scala._ improving things as I could. However, not all classes are
> created equal and some might need more attention as far as documentation
> goes than others.
>
> Can anyone point out some classes in the core library that need
> particular documentation improvements or where the docs are particularly
> wrong or confusing? Or, put another way, which core classes were the
> most difficult to understand the first time you needed to use them?
>
> Thanks,
>
> Dave
>
> ---
> My Blog: http://www.naildrivin5.com/blog
> Scala Tour for Java Developers: http://www.naildrivin5.com/scalatour
> Fork me on Github: http://davetron5000.github.com
>

Dave,

Tangentially off topic:

If you are doing this using Vim, may I suggest using
scalacommenter.vim
http://www.vim.org/scripts/script.php?script_id=3047
which might help with the formatting and @ tag generation parts of
a scaladoc comment.
Also, seeing that you are actually creating/editing some of Scala's
core library scaladocs, if you have any usage or formatting
suggestions I can add to the tool to make it more useful
I would be much appreciative.
For instance, which tags should be supported? What should
the order of the tags be? In a javadoc comment, the text does
not start on the the first line, "/**", but it seems that
in the Scala libraries the scaladoc comment text does start on
the first line ... should that be the default behavior? Etc. etc.

Thanks.


Richard

On 08/16/2010 11:29 AM, David Copeland wrote:

My very slow quest to improve the core library scaladoc is off to a good
start.  I was planning to just go through each class, starting in
scala._ improving things as I could.  However, not all classes are
created equal and some might need more attention as far as documentation
goes than others.

Can anyone point out some classes in the core library that need
particular documentation improvements or where the docs are particularly
wrong or confusing?  Or, put another way, which core classes were the
most difficult to understand the first time you needed to use them?

Thanks,

Dave

---
My Blog: http://www.naildrivin5.com/blog
Scala Tour for Java Developers: http://www.naildrivin5.com/scalatour
Fork me on Github: http://davetron5000.github.com