- About Scala
- Documentation
- Code Examples
- Software
- Scala Developers
Scaladoc that is actually useful?
(observations based on 2.7.7 - feel free to say that something will be
better in 2.8 but only if it actually is)
I'm new to Scala but have been using Java for more than 10 years now.
One of the stumbling blocks that I am running into learning the
language is that the Scaladoc for many of the library classes is
nearly useless. The mutable LinkedList, for example is almost
impossible for a newbie to use because it is so completely unlike most
Java collections and the constructor is not listed in the Scaladoc.
So why aren't constructors listed in the Scaladoc? (though I haven't
yet progressed to the point where the syntax for the LinkedList class
makes sense yet, even if I have figured out how to use it)
And maybe some actual, even useful, descriptive text? If the answer is
"well, nobody has gotten around to it yet," I can understand that (and
will probably volunteer to help correct the problem, just as soon as I
can understand it myself)
Re: Re: Scaladoc that is actually useful?
On Sunday November 15 2009, Peter C. Chapin wrote:
> andrew cooke wrote
>
> in news:4ca747c30911121304v4714b37ey8c656249e0a6fa40 [at] mail [dot] gmail [dot] com:
> >> e.g. What would you (could you possibly) write for this function?
> >> def boo[A, B, C](f: A => B, g: B => C): A => C
> >
> > i believe that there are a lot of people out there who cannot look
> > at that signature and immediately infer what the function does. an
> > explanation like "Join two functions together as one so that the
> > results from calling the first are then evaluated by the second"
It seems a lot easier and is clearly more concise to say that it
computes the composition of its arguments.
> How do you know it does that? I see a function that takes two
> functions as parameters and returns a function. What is it about that
> signature that explains the relationship between the returned
> function and the functions provided as parameters? Oh sure the types
> *suggest* the relationship you mentioned but they do not prove it.
Do you really want to start this again? In that particular case, the
only function that does not violate the express typing specified is
function composition. That is not always the case, clearly, or we could
write compilers that used only type signatures to generate code.
> I agree with you, Andrew, and disagree with Tony, in that English
> documentation must be associated with the signature above to describe
> the semantics of the function.
If what the method or function computes is at odds with its signature,
then your program (probably) contains a bug (though that bug, if
present, may not be manifest much or ever, but it lurks, waiting to
pounce when the type lie is exposed). If the type signature is a lie,
the compiler can't protect you from those bugs. That is _why_ we want a
rich type system. It helps us say what we really mean by forcing us to
mean what we say, but if we lie about types, it cannot do that.
> If one has a mathematical inclination
> then perhaps some sort of formal specification language could be used
> (Z?). However the interface needed by the compiler is not sufficient
> to describe the function's (possibly complex and non-obvious)
> internal operation.
No, in general a type signature, whether Haskell or Scala, to pick two
examples, does not specify an algorithm, but it does _constrain_ them
(and in particular cases, does constrain them down to singularity), and
Tony rightly asserts that the type signature is the proper starting
point for stating or understanding what any given method or function
computes. This perspective is reinforced by the fact that the type
signature is the first thing we must put down when writing a method.
> Peter
Randall Schulz
Re: Scaladoc that is actually useful?
I strongly disagree. I do not pander to ill-education. Indeed, as a
lecturer, I have been strongly advocating a course on type theory in
universities for many years.
If an English description of a once-inhabited type "makes things
clearer" then it certainly doesn't belong in an API specification. It
belongs in an introductory text book. It's redundant at best, and often
erroneous and ambiguous. It conveys no useful information whatsoever
above what is already conveyed. An API specification is not a place to
repeat yourself in a degenerate fashion.
I think you should seriously consider your position, since your apathy
and indirect advocacy for poor education is part of the problem, not the
solution.
andrew cooke wrote:
> 2009/11/12 Tony Morris :
>
>> The constructor is listed for LinkedList (and all classes).
>>
>> Descriptive text in API documentation is not virtuous, quite the
>> contrary. Aim to read from the types first, (proper) specification tests
>> second, English if you insist.
>>
>> e.g. What would you (could you possibly) write for this function?
>> def boo[A, B, C](f: A => B, g: B => C): A => C
>>
>> Not even tests.
>>
>> There are other valid criticisms of scaladoc -- these are not.
>>
>
> i'm afraid i disagree quite strongly.
>
> i believe that there are a lot of people out there who cannot look at
> that signature and immediately infer what the function does. an
> explanation like "Join two functions together as one so that the
> results from calling the first are then evaluated by the second" would
> make things clearer for them. at the very least it would give them
> the confirmation that they have inferred correctly if they lacked
> confidence, and so help educate the user base.
>
> i think you should seriously reconsider your position - from where i
> am standing (which is a position of sympathy for scala, and with a
> fair amount of professional experience) you are part of the problem,
> not the solution.
>
> andrew
>
>
RE: Scaladoc that is actually useful?
> I strongly disagree. I do not pander to ill-education. Indeed, as a
> lecturer, I have been strongly advocating a course on type theory in
> universities for many years.
Why bother lecturing at all? Can't your students just be pointed at the ones and zeros and left to figure it out for themselves? Perhaps there is something wrong with their brains?
New! Receive and respond to mail from other email accounts from within Hotmail Find out how.
Re: Scaladoc that is actually useful?
2009/11/12 Tony Morris :
> I strongly disagree. I do not pander to ill-education. Indeed, as a
> lecturer, I have been strongly advocating a course on type theory in
> universities for many years.
yep. this is the problem.
scala is perhaps the one chance in my professional lifetime for me to
get to use, at work, a language with a modern, powerful type system.
the only way that is going to happen is if either:
1 - you educate my co-workers
2 - the docs change so that my co-workers understand them
i don't think 1 is going to happen.
look, take haskell. go educate people with that. let scala have a
chance to be successful.
andrew
Re: Scaladoc that is actually useful?
On Thu, 2009-11-12 at 18:26 -0300, andrew cooke wrote:
> look, take haskell. go educate people with that. let scala have a
> chance to be successful.
You realise that Tony doesn't influence what goes into the scaladoc for
the standard library, right?
As far as I know, Martin and others are not against fleshing out the
scaladoc, they just haven't had the time and no-one else has done it
either.
Best,
Ismael
Re: Scaladoc that is actually useful?
I don't accept the argument that poor education is a good reason to
commit errors. It's also unlikely that is going to change.
Hope it works out in any case.
andrew cooke wrote:
> 2009/11/12 Tony Morris :
>
>> I strongly disagree. I do not pander to ill-education. Indeed, as a
>> lecturer, I have been strongly advocating a course on type theory in
>> universities for many years.
>>
>
> yep. this is the problem.
>
> scala is perhaps the one chance in my professional lifetime for me to
> get to use, at work, a language with a modern, powerful type system.
> the only way that is going to happen is if either:
>
> 1 - you educate my co-workers
> 2 - the docs change so that my co-workers understand them
>
> i don't think 1 is going to happen.
>
> look, take haskell. go educate people with that. let scala have a
> chance to be successful.
>
> andrew
>
>
Re: Scaladoc that is actually useful?
It's not just the "nobody got around to it yet". It is also the fact
that you have to switch between class and object pages,
and--particularly with the 2.8 collections API--that you are exposed
to a rather complex set of traits that the casual library user
shouldn't have to know about. See
http://stackoverflow.com/questions/1722726/is-the-scala-2-8-collections-....
I have no answer; I just want to register my violent agreement that
there is a problem.
On Thu, Nov 12, 2009 at 11:08 AM, Donald McLean wrote:
> (observations based on 2.7.7 - feel free to say that something will be
> better in 2.8 but only if it actually is)
>
> I'm new to Scala but have been using Java for more than 10 years now.
> One of the stumbling blocks that I am running into learning the
> language is that the Scaladoc for many of the library classes is
> nearly useless. The mutable LinkedList, for example is almost
> impossible for a newbie to use because it is so completely unlike most
> Java collections and the constructor is not listed in the Scaladoc.
>
> So why aren't constructors listed in the Scaladoc? (though I haven't
> yet progressed to the point where the syntax for the LinkedList class
> makes sense yet, even if I have figured out how to use it)
>
> And maybe some actual, even useful, descriptive text? If the answer is
> "well, nobody has gotten around to it yet," I can understand that (and
> will probably volunteer to help correct the problem, just as soon as I
> can understand it myself)
> --
> Family photographs are a critical legacy for
> ourselves and our descendants. Protect that
> legacy with a digital backup and recovery plan.
>
> Join the photo preservation advocacy Facebook group:
> http://www.facebook.com/home.php?ref=logo#/group.php?gid=148274709288
>
Re: Scaladoc that is actually useful?
There's also no way of knowing from the Scaladoc of a class whether or not
there are any handy implicit conversions you could import in that would make
the class more useful. The thing about Javadoc is that understanding the
Javadoc and a couple of usage examples is pretty much all you needed in
order to use most Java classes. That's not the case with Scaladoc, and it
is seriously missed.
(Yes, I realize that this is a tricky problem in as much as HTML doesn't
have anyway of handling external annotations. That doesn't mean it isn't a
serious problem.)
Cay Horstmann wrote:
>
>
> I have no answer; I just want to register my violent agreement that
> there is a problem.
>
Re: Scaladoc that is actually useful?
+1 on that.
I think the lack of decent API documentation is one of the most
disappointing aspects of Scala.