This page is no longer maintained — Please continue to the home page at www.scala-lang.org

(Collection) Scaladoc feedback

1 reply
fanf
Joined: 2009-03-17,
User offline. Last seen 2 years 30 weeks ago.
Hello guys,

Just a little message to report some more feedbacks about Scala API documentation, and especially collection API:

  • use cases are really helpful, even if not perfect. It seems hard to people I talked to to explain "not perfect", but maybe:
    • adding concrete examples will help - most of the time, even the use case signature does not seems crystal clear, but as soon as an use case example is given, that ring a bell
    • adding link to source code of the method, to understand what is really going on (but I understand that it may be quite hard to show relevant code for a given method...)
    • well, in the end, the real signature is not the one of the use case, and that is intriguing (both good in bad)
  • it would help a lot if methods could be grouped by role, as it was done in "The Scala 2.8 Collections API" documentation (for example: http://www.scala-lang.org/docu/files/collections-api/collections_7.html). Most of the time, users don't really know the name of the method they are looking for (zipWithIndex ? Really ?), but they have an idea of the role/kind of method they are looking for.

Hope it helps,

-- 
Francois ARMAND
http://fanf42.blogspot.com
http://www.normation.com
vpatryshev
Joined: 2009-02-16,
User offline. Last seen 1 year 24 weeks ago.
Re: (Collection) Scaladoc feedback
I absolutely concure.
Or, alternatively, meanwhile, one can just create a reference wiki page with all this.
Would be good too.

Thanks,
-Vlad


On Mon, Nov 28, 2011 at 3:34 AM, Francois <fanf42 [at] gmail [dot] com> wrote:
Hello guys,

Just a little message to report some more feedbacks about Scala API documentation, and especially collection API:

  • use cases are really helpful, even if not perfect. It seems hard to people I talked to to explain "not perfect", but maybe:
    • adding concrete examples will help - most of the time, even the use case signature does not seems crystal clear, but as soon as an use case example is given, that ring a bell
    • adding link to source code of the method, to understand what is really going on (but I understand that it may be quite hard to show relevant code for a given method...)
    • well, in the end, the real signature is not the one of the use case, and that is intriguing (both good in bad)
  • it would help a lot if methods could be grouped by role, as it was done in "The Scala 2.8 Collections API" documentation (for example: http://www.scala-lang.org/docu/files/collections-api/collections_7.html). Most of the time, users don't really know the name of the method they are looking for (zipWithIndex ? Really ?), but they have an idea of the role/kind of method they are looking for.

Hope it helps,

-- 
Francois ARMAND
http://fanf42.blogspot.com
http://www.normation.com

Copyright © 2012 École Polytechnique Fédérale de Lausanne (EPFL), Lausanne, Switzerland