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

Scaladoc that is actually useful?

59 replies
Donald McLean
Joined: 2009-11-11,
User offline. Last seen 2 years 48 weeks ago.

(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)

Cay Horstmann
Joined: 2009-09-04,
User offline. Last seen 42 years 45 weeks ago.
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
>

Luan O'Carroll
Joined: 2009-10-30,
User offline. Last seen 42 years 45 weeks ago.
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.

Tony Morris 2
Joined: 2009-03-20,
User offline. Last seen 42 years 45 weeks ago.
Re: Scaladoc that is actually useful?

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.

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)
>

andrew cooke 2
Joined: 2009-10-24,
User offline. Last seen 42 years 45 weeks ago.
Re: Scaladoc that is actually useful?

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

Tony Morris 2
Joined: 2009-03-20,
User offline. Last seen 42 years 45 weeks ago.
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
>
>

anli
Joined: 2008-08-19,
User offline. Last seen 1 day 37 min ago.
Re: Scaladoc that is actually useful?

On Thursday 12 November 2009 23:55:16 Tony Morris wrote:
> 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.

Tony,

When you are going to publish "Functional Scala for Java dammies" book?
All timelines have gone already.. gr-r-r-r... Ugh, Tony, I was too fast. Stop
writing the book! - I know, the most used chars are '[' and ']' there :-)

Seriously, information (articles, blog posts, and so on) of such kind is
rather scattered. It is common case when I want to understand something, I
read this article (without big clue), that one (with the same effect), but at
some point tiny correlation between these and those dark spots is discovered,
and, still being vague, some ideas begin to shine humbly.

Andrew

andrew cooke 2
Joined: 2009-10-24,
User offline. Last seen 42 years 45 weeks ago.
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

Tony Morris 2
Joined: 2009-03-20,
User offline. Last seen 42 years 45 weeks ago.
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
>
>

ijuma
Joined: 2008-08-20,
User offline. Last seen 22 weeks 2 days ago.
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

David Copeland
Joined: 2009-06-16,
User offline. Last seen 42 years 45 weeks ago.
Re: Scaladoc that is actually useful?
I, too, think the Scaladoc is woefully terse and hard to navigate. 

It is very difficult to open up a package and decide what it does and where to get started using it.  There is no package.html concept, nor is there a way to filter out the various helper classes.

As to Tony's aggresive stance on obfuscation, I couldn't agree with him less.  The Javadocs are wonderful in many cases, and you can determine how to use the various packages in almost all cases by reading them.

Scaladoc, on the other hand, is not this way.  One should not have to read the source to determine what a call is intended to do; look at Actor.receive and Actor.react - exact same documentation string, but they do totally different things (I am told).

Look also at the Rails Rubydoc; not as nice as Javadoc, but you can dig deep into the API without having a book nor reading the source, because the documentation is so well-written.

Further, why SHOULDN'T the documentation be focused toward newcomers?  They are the exact target audience for this stuff, and a short example will go a long way.

Let's look at Either.fold:

fold[X](fa : (A) => X, fb : (B) => X) : X

"Deconstruction of the Either type (in contrast to pattern matching)."

I have no idea what that means.  In fact, what it does is "calls fa if this is a left, and fb if this is a right".  So how about:

fold[X](fl : (L) => X, fr: (R) => X) : X

  Calls fl if isLeft is true, or fr is isRight is true

I don't see what is so offensive about this, nor why it's so horrible to make the documentation accessible to newcomers.

I think some would gladly contribute (I would), but if Tony's attitude is the general one, I doubt anyone would want to appear "ill-educated" by explaining some of the library classes and methods.

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



On Thu, Nov 12, 2009 at 4:17 PM, Andrew Gaydenko <a [at] gaydenko [dot] com> wrote:
On Thursday 12 November 2009 23:55:16 Tony Morris wrote:
> 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.

Tony,

When you are going to publish "Functional Scala for Java dammies" book?
All timelines have gone already.. gr-r-r-r... Ugh, Tony, I was too fast. Stop
writing the book! - I know, the most used chars are '[' and ']' there :-)

Seriously, information (articles, blog posts, and so on) of such kind is
rather scattered. It is common case when I want to understand something, I
read this article (without big clue), that one (with the same effect), but at
some point tiny correlation between these and those dark spots is discovered,
and, still being vague, some ideas begin to shine humbly.


Andrew

Tony Morris 2
Joined: 2009-03-20,
User offline. Last seen 42 years 45 weeks ago.
Re: Scaladoc that is actually useful?

Some points.

* "Making a bit of sense" or "failing to appease the norm" does not
imply "aggression."
* Ruby documentation does not contain types. No wonder it is full of
English.
* Java does not possess a practical type system. No wonder it is full of
English.
* By "newcomer" I mean, "new to programming", not Scala. If you don't
understand some of the fundamentals of programming, then read a book,
not an API specification (I'll even help you, like I said -- I enjoy
teaching).

forall A B C. (A => B) => (B => C) => A => C

This is both a function signature and a logical statement. It *says
something*. In fact, it says so much there is nothing more to be said
without redundancy or error.

I hope this helps. If it doesn't, I'm out.

David Copeland wrote:
> I, too, think the Scaladoc is woefully terse and hard to navigate.
>
> It is very difficult to open up a package and decide what it does and
> where to get started using it. There is no package.html concept, nor
> is there a way to filter out the various helper classes.
>
> As to Tony's aggresive stance on obfuscation, I couldn't agree with
> him less. The Javadocs are wonderful in many cases, and you can
> determine how to use the various packages in almost all cases by
> reading them.
>
> Scaladoc, on the other hand, is not this way. One should not have to
> read the source to determine what a call is intended to do; look at
> Actor.receive and Actor.react - exact same documentation string, but
> they do totally different things (I am told).
>
> Look also at the Rails Rubydoc; not as nice as Javadoc, but you can
> dig deep into the API without having a book nor reading the source,
> because the documentation is so well-written.
>
> Further, why SHOULDN'T the documentation be focused toward newcomers?
> They are the exact target audience for this stuff, and a short example
> will go a long way.
>
> Let's look at Either.fold:
>
> /fold/[/X/](/fa/ : (A
> ) => X
> ,
> /fb/ : (B
> ) => X
> )
> : X
>
>
> "Deconstruction of the |Either| type (in contrast to pattern matching)."
>
> I have no idea what that means. In fact, what it does is "calls fa if
> this is a left, and fb if this is a right". So how about:
>
> fold[X](fl : (L) => X, fr: (R) => X) : X
>
> Calls fl if isLeft is true, or fr is isRight is true
>
> I don't see what is so offensive about this, nor why it's so horrible
> to make the documentation accessible to newcomers.
>
> I think some would gladly contribute (I would), but if Tony's attitude
> is the general one, I doubt anyone would want to appear "ill-educated"
> by explaining some of the library classes and methods.
>
> 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
>
>
>
> On Thu, Nov 12, 2009 at 4:17 PM, Andrew Gaydenko > wrote:
>
> On Thursday 12 November 2009 23:55:16 Tony Morris wrote:
> > 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.
>
> Tony,
>
> When you are going to publish "Functional Scala for Java dammies"
> book?
> All timelines have gone already.. gr-r-r-r... Ugh, Tony, I was too
> fast. Stop
> writing the book! - I know, the most used chars are '[' and ']'
> there :-)
>
> Seriously, information (articles, blog posts, and so on) of such
> kind is
> rather scattered. It is common case when I want to understand
> something, I
> read this article (without big clue), that one (with the same
> effect), but at
> some point tiny correlation between these and those dark spots is
> discovered,
> and, still being vague, some ideas begin to shine humbly.
>
>
> Andrew
>
>

Dave Griffith
Joined: 2009-01-14,
User offline. Last seen 42 years 45 weeks ago.
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.
>

ichoran
Joined: 2009-08-14,
User offline. Last seen 2 years 3 weeks ago.
Re: Scaladoc that is actually useful?
On Thu, Nov 12, 2009 at 3:55 PM, Tony Morris <tonymorris [at] gmail [dot] com> wrote:
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

That one?  I don't know--it's titled "boo", so it should be a surprise.  Maybe it returns a function that prints out "Boo!" and returns null.  Maybe it returns the BooException and never completes normally.

How about this one?

def printIntermediate[A,B,C](f: A => B, g: B => C): A => C

Same type signature.  Maybe it, I don't know, creates a function that prints out the intermediate result of type B in addition to doing the function composition?

How about

def nullCatch[A,B,C](f: A => B, g: B => C): A => C

Same type signature again.  This might possibly catch if inputs are null and throw null outputs rather than throwing exceptions, in addition to composing the functions.

If you don't document your functions, how are people supposed to know whether and what side effects there are, and whether the function is value-added (as in nullCatch) or not (as in the straightforward function-composition boo that I assume you were imagining)?

  --Rex

Dave Griffith
Joined: 2009-01-14,
User offline. Last seen 42 years 45 weeks ago.
Re: Scaladoc that is actually useful?

Tony Morris-4 wrote:
>
> 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.
>

def boo[A, B, C](f: A => B, g: B => C): A => C = {

reformatHardDrive();

emptyBankAccount();

error("gotcha")
}

Not sure I agree 100% with your QA work there.

--Dave Griffith

dcsobral
Joined: 2009-04-23,
User offline. Last seen 38 weeks 5 days ago.
Re: Scaladoc that is actually useful?
While Tony is being Tony -- he wants people to think in ways most people don't -- and without disagreeing about the rather lackluster state of Scala's API documentation, here's the thing about constructors: the default constructor is the class declaration itself. If there are others, they are listed apart.
Here's what I see for LinkedList on Scala 2.7.4:
class LinkedList[A](val elem : Aval next : LinkedList[A])
extends SingleLinkedList[ALinkedList[A]]
This class implements single linked lists where both the head (elem) and the tail (next) are mutable.
So I construct it by passing the "elem" (or "head") and the "next" (or "tail") of the list. Not brilliant, but serviceable.
On Thu, Nov 12, 2009 at 3:08 PM, Donald McLean <dmclean62 [at] gmail [dot] com> 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



--
Daniel C. Sobral

Veni, vidi, veterni.
Chris Marshall
Joined: 2009-06-17,
User offline. Last seen 44 weeks 3 days ago.
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.
Tony Morris 2
Joined: 2009-03-20,
User offline. Last seen 42 years 45 weeks ago.
Re: Scaladoc that is actually useful?

Andrew, I have just spent 14 months at war with pragmatism and other
forms of stupidity in the medical establishment.

I've no idea what my plans are now that I have won, or what they were
before I was forced to war, except perhaps for the obvious complaint to
the medical health authority, which is likely to take up much of my time.

Andrew Gaydenko wrote:
> On Thursday 12 November 2009 23:55:16 Tony Morris wrote:
>
>> 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.
>>
>
> Tony,
>
> When you are going to publish "Functional Scala for Java dammies" book?
> All timelines have gone already.. gr-r-r-r... Ugh, Tony, I was too fast. Stop
> writing the book! - I know, the most used chars are '[' and ']' there :-)
>
> Seriously, information (articles, blog posts, and so on) of such kind is
> rather scattered. It is common case when I want to understand something, I
> read this article (without big clue), that one (with the same effect), but at
> some point tiny correlation between these and those dark spots is discovered,
> and, still being vague, some ideas begin to shine humbly.
>
>
> Andrew
>
>

Dmitry Grigoriev
Joined: 2009-07-12,
User offline. Last seen 42 years 45 weeks ago.
Re: Scaladoc that is actually useful?

Hello, Tony, you said:
> forall A B C. (A => B) => (B => C) => A => C

Real libs are a bit more complex, don't you think? In both type system
and logic.

Yesterday, after two evenings of digging into combinator
token/scanner/parser stuff (no docs, no simple examples, many source
files in various subpackages), I got stack overflow in my head, gave up
and used basic simple combinator.Parsers. Also, you were already given
an example about actors. Do you really think that such a complex thing
like concurrency can be explained just in type system? Poor, very poor.

Type system itself may look quite descriptive. For its author. Or for
PhD. If you want language to be popular among other folk, you cannot
avoid redundancy. And must not. "Repetition - mother of studying" (c)
russian saying. Good documentation repeates same things in same or
different words in every relevant context. Even same paragraphs
copy-pasted. Javadoc + java tutorial is good example.

On the other hand, ScalaDOC is currently not DOC at all. It's nothing
more than just a collection of Eclipse outline views. Reminds me Ferma's
"I proved this wonderful theorem but here's too few place to write down
the proof" (sorry for inexact quoting). Or popular joke "if author says
'it's evident that...' be sure he omitted the most heavy part of proof".
It's absolutely useless except for simple cases (simple == intuitively
understandable to average programmer). And also there's no complete
tutorial at all. There's a book which is great but not exhaustive. And
there's Google, lots of scattered articles and mailing list archives.

I +1000 agree with David Copeland's message above: currently Scala is
very difficult to study. Please understand: you're creating language not
for PhDs. Programmer must be productive. We must code, not fight with
terrible docs or continuously raise our googling skills. We want to find
method by name (or rollover it in IDE) and see all details of its
operation. Now. If you don't change your approach about language
documentation, you'll bury the language itself, be sure.

Tony Morris 2
Joined: 2009-03-20,
User offline. Last seen 42 years 45 weeks ago.
Re: Re: Scaladoc that is actually useful?

Not "real" libraries, but some signatures are inhabited more than once.
De ja vu.

I agree entirely, the programmer must be productive. This is precisely
why I refuse to pander to the "I am not educated on this trivial and
highly relevant matter" excuse. Harden up and get educated!

Dmitry Grigoriev wrote:
> Hello, Tony, you said:
>
>> forall A B C. (A => B) => (B => C) => A => C
>>
>
> Real libs are a bit more complex, don't you think? In both type system
> and logic.
>
> Yesterday, after two evenings of digging into combinator
> token/scanner/parser stuff (no docs, no simple examples, many source
> files in various subpackages), I got stack overflow in my head, gave up
> and used basic simple combinator.Parsers. Also, you were already given
> an example about actors. Do you really think that such a complex thing
> like concurrency can be explained just in type system? Poor, very poor.
>
> Type system itself may look quite descriptive. For its author. Or for
> PhD. If you want language to be popular among other folk, you cannot
> avoid redundancy. And must not. "Repetition - mother of studying" (c)
> russian saying. Good documentation repeates same things in same or
> different words in every relevant context. Even same paragraphs
> copy-pasted. Javadoc + java tutorial is good example.
>
> On the other hand, ScalaDOC is currently not DOC at all. It's nothing
> more than just a collection of Eclipse outline views. Reminds me Ferma's
> "I proved this wonderful theorem but here's too few place to write down
> the proof" (sorry for inexact quoting). Or popular joke "if author says
> 'it's evident that...' be sure he omitted the most heavy part of proof".
> It's absolutely useless except for simple cases (simple == intuitively
> understandable to average programmer). And also there's no complete
> tutorial at all. There's a book which is great but not exhaustive. And
> there's Google, lots of scattered articles and mailing list archives.
>
> I +1000 agree with David Copeland's message above: currently Scala is
> very difficult to study. Please understand: you're creating language not
> for PhDs. Programmer must be productive. We must code, not fight with
> terrible docs or continuously raise our googling skills. We want to find
> method by name (or rollover it in IDE) and see all details of its
> operation. Now. If you don't change your approach about language
> documentation, you'll bury the language itself, be sure.
>
>

Ben Hutchison 3
Joined: 2009-11-02,
User offline. Last seen 42 years 45 weeks ago.
Re: Scaladoc that is actually useful?

On Fri, Nov 13, 2009 at 4:08 AM, Donald McLean wrote:
> 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.

Given the strong support for the "Scaladoc is not useful" position in
this thread, I feel compelled to simply say that I find the Scaladoc
quite useful.

More explanation will be nice when it comes, but generally I'd rather
the time was spent on addressing trac issues than writing more
scaladoc.

Ive been learning Scala for about 15 months. Earlier on, I did find
the Scaladoc less easy to understand, but as my knowledge of Scala has
grown, the scaladocs are progressively more useful.

If you want to /learn/ Scala, as opposed to /use it having already
learned it/, "Programming in Scala" is a thoroughly excellent book.

-Ben

Meredith Gregory
Joined: 2008-12-17,
User offline. Last seen 42 years 45 weeks ago.
Re: Scaladoc that is actually useful?
Dear Tony,

i'm just stumbling onto this thread. i have great sympathy for the sense that programming with types provides much greater clarity and that in very highly expressive systems like Scala's we have the opportunity to be much more precise. Further, experience has so jaded me that i almost never read documentation. It's usually wrong. However, there is an implicit position in your argumentation here that is a little troubling. The position is that there is no interesting or useful information between type and implementation that can be conveyed without redundancy or without revealing implementation details that should remain hidden. This is certainly false. Curry-Howard tells us that
  • program : type :: proof : formula
It doesn't make uniqueness claims. Just as there are many many proofs of the same formula there are many, many programs that inhabit the same type. Here's a type: List[Ordered[T]] => List[Ordered[T]]. It has lots of inhabitants. It's certainly not clear from this type whether i want to utilize in my application context the particular inhabitant an API is offering. Even if the API says sort : List[Ordered[T]] => List[Ordered[T]] it might not be what i want. What is meant by sort might still not be in alignment with my application's requirements. 

Documentation can very much help the user if it provides a compressed description of the essential aspects of proof/program that either are not expressible in the type system or haven't been captured in the type for pragmatic reasons. Here are some such that can be extremely helpful guidance in an API.
  • family of algorithm -- many algorithms are actually a part of a naturally collected family that vary in a parameter either not captured by the type or not exposed in the API, for example the GARCH family of algorithms or the VAR family of algorithms. Methods for approximating integration are another.
  • complexity -- many algorithms enjoy complexity trade-offs, cf quick sort and bubble sort, that are relevant to the client of the API. Until Scala starts providing linear types or sophisticated effects systems or both these are not even expressible at the type level. Even if they had such sophisticated machinery it's questionable that you want to express such trade-offs in the type system.
  • boundary conditions -- we work on machines with limitations, it's useful to know what an API does when it hits one of those. Again, this is often not expressed in the type system. For example, Int and Float are both type that hide boundaries. It's a really good idea to know how a function handles hitting one of those.

FWIW, i found and often still find the scaladocs to be indispensable to programming Scala. They contain exactly the information i need -- usually -- to make the determination about which API i need to employ for my purposes.

Best wishes,

--greg

On Thu, Nov 12, 2009 at 2:00 PM, Tony Morris <tonymorris [at] gmail [dot] com> wrote:
Some points.

* "Making a bit of sense" or "failing to appease the norm" does not
imply "aggression."
* Ruby documentation does not contain types. No wonder it is full of
English.
* Java does not possess a practical type system. No wonder it is full of
English.
* By "newcomer" I mean, "new to programming", not Scala. If you don't
understand some of the fundamentals of programming, then read a book,
not an API specification (I'll even help you, like I said -- I enjoy
teaching).

forall A B C. (A => B) => (B => C) => A => C

This is both a function signature and a logical statement. It *says
something*. In fact, it says so much there is nothing more to be said
without redundancy or error.

I hope this helps. If it doesn't, I'm out.


David Copeland wrote:
> I, too, think the Scaladoc is woefully terse and hard to navigate.
>
> It is very difficult to open up a package and decide what it does and
> where to get started using it.  There is no package.html concept, nor
> is there a way to filter out the various helper classes.
>
> As to Tony's aggresive stance on obfuscation, I couldn't agree with
> him less.  The Javadocs are wonderful in many cases, and you can
> determine how to use the various packages in almost all cases by
> reading them.
>
> Scaladoc, on the other hand, is not this way.  One should not have to
> read the source to determine what a call is intended to do; look at
> Actor.receive and Actor.react - exact same documentation string, but
> they do totally different things (I am told).
>
> Look also at the Rails Rubydoc; not as nice as Javadoc, but you can
> dig deep into the API without having a book nor reading the source,
> because the documentation is so well-written.
>
> Further, why SHOULDN'T the documentation be focused toward newcomers?
> They are the exact target audience for this stuff, and a short example
> will go a long way.
>
> Let's look at Either.fold:
>
> /fold/[/X/](/fa/ : (A
> <http://www.scala-lang.org/docu/files/api/scala/Either.html#A>) => X
> <http://www.scala-lang.org/docu/files/api/scala/Either.html#fold%28%28A%29%3D%3EX%2C%28B%29%3D%3EX%29#X>,
> /fb/ : (B
> <http://www.scala-lang.org/docu/files/api/scala/Either.html#B>) => X
> <http://www.scala-lang.org/docu/files/api/scala/Either.html#fold%28%28A%29%3D%3EX%2C%28B%29%3D%3EX%29#X>)
> : X
> <http://www.scala-lang.org/docu/files/api/scala/Either.html#fold%28%28A%29%3D%3EX%2C%28B%29%3D%3EX%29#X>
>
> "Deconstruction of the |Either| type (in contrast to pattern matching)."
>
> I have no idea what that means.  In fact, what it does is "calls fa if
> this is a left, and fb if this is a right".  So how about:
>
> fold[X](fl : (L) => X, fr: (R) => X) : X
>
>   Calls fl if isLeft is true, or fr is isRight is true
>
> I don't see what is so offensive about this, nor why it's so horrible
> to make the documentation accessible to newcomers.
>
> I think some would gladly contribute (I would), but if Tony's attitude
> is the general one, I doubt anyone would want to appear "ill-educated"
> by explaining some of the library classes and methods.
>
> 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
>
>
>
> On Thu, Nov 12, 2009 at 4:17 PM, Andrew Gaydenko <a [at] gaydenko [dot] com
> <mailto:a [at] gaydenko [dot] com>> wrote:
>
>     On Thursday 12 November 2009 23:55:16 Tony Morris wrote:
>     > 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.
>
>     Tony,
>
>     When you are going to publish "Functional Scala for Java dammies"
>     book?
>     All timelines have gone already.. gr-r-r-r... Ugh, Tony, I was too
>     fast. Stop
>     writing the book! - I know, the most used chars are '[' and ']'
>     there :-)
>
>     Seriously, information (articles, blog posts, and so on) of such
>     kind is
>     rather scattered. It is common case when I want to understand
>     something, I
>     read this article (without big clue), that one (with the same
>     effect), but at
>     some point tiny correlation between these and those dark spots is
>     discovered,
>     and, still being vague, some ideas begin to shine humbly.
>
>
>     Andrew
>
>

--
Tony Morris
http://tmorris.net/





--
L.G. Meredith
Managing Partner
Biosimilarity LLC
1219 NW 83rd St
Seattle, WA 98117

+1 206.650.3740

http://biosimilarity.blogspot.com
Randall R Schulz
Joined: 2008-12-16,
User offline. Last seen 1 year 29 weeks ago.
Re: Scaladoc that is actually useful?

On Friday November 13 2009, Meredith Gregory wrote:
> Dear Tony,
>
> ... However, there is an implicit position in your argumentation here
> that is a little troubling. The position is that there is no
> interesting or useful information between type and implementation
> that can be conveyed without redundancy or without revealing
> implementation details that should remain hidden. ...

I'm pretty sure the particular case of composing two arbitrary functions
was just one example that Tony chose specifically 'cause it is simple
enough to exhibit the property that the type signature alone fully
constrains what a truly conforming method can compute.

Randall Schulz

phkoester
Joined: 2009-08-23,
User offline. Last seen 42 years 45 weeks ago.
Re: Scaladoc that is actually useful?

On a side note for this lengthy and vibrant discussion, I'd like to have
a Scaladoc *tool* that is more useful, e.g. one that supports {@link},
{@linkplain}, {@code} and such---that is, all the tags that Javadoc has.

---Ph.

Meredith Gregory
Joined: 2008-12-17,
User offline. Last seen 42 years 45 weeks ago.
Re: Scaladoc that is actually useful?
Dear Randall,

Does it? Under linear decomposition:

A => B = !A -o B = ?¬A # B

we get that theorem, but i can think of lots and lots of realizations that have very different complexity results. Without using linear decomposition we have for each integer k

f o_k g = { val d = computeKthDigitOfPi( k); println( d ); f o g } : (A => B) => (B => C) => A => C

That's a lot of different inhabitants of that type. The reason i mention the linear decomposition is because while the family in the line above is pretty silly and only there to make a point, the universe of interpretations in linear categories is full of very interesting and useful alternatives which still provide proof of the theorem.

Types say a lot of interesting things, but what they don't and shouldn't say is every little thing about the program. There may still be interesting and useful information about the program that is worthwhile to be captured in documentation.

Best wishes,

--greg

On Fri, Nov 13, 2009 at 9:27 AM, Randall R Schulz <rschulz [at] sonic [dot] net> wrote:
On Friday November 13 2009, Meredith Gregory wrote:
> Dear Tony,
>
> ... However, there is an implicit position in your argumentation here
> that is a little troubling. The position is that there is no
> interesting or useful information between type and implementation
> that can be conveyed without redundancy or without revealing
> implementation details that should remain hidden. ...

I'm pretty sure the particular case of composing two arbitrary functions
was just one example that Tony chose specifically 'cause it is simple
enough to exhibit the property that the type signature alone fully
constrains what a truly conforming method can compute.


Randall Schulz



--
L.G. Meredith
Managing Partner
Biosimilarity LLC
1219 NW 83rd St
Seattle, WA 98117

+1 206.650.3740

http://biosimilarity.blogspot.com
Bastian, Mark
Joined: 2009-01-16,
User offline. Last seen 42 years 45 weeks ago.
Re: Scaladoc that is actually useful?
Re: [scala-user] Scaladoc that is actually useful? While we are at it, may I request a documentation tool that extracts documentation from mixed Scala/Java projects.

Regarding the debate, my suggestion would be to concisely document that which is confusing and let the method signatures be the docs where no confusion exists. Crazy talk, I know.

-Mark

On 11/13/09 10:52 AM, "Philip Köster" <philip [dot] koester [at] web [dot] de" rel="nofollow">philip [dot] koester [at] web [dot] de> wrote:

On a side note for this lengthy and vibrant discussion, I'd like to have
a Scaladoc *tool* that is more useful, e.g. one that supports {@link},
{@linkplain}, {@code} and such---that is, all the tags that Javadoc has.

---Ph.


Donald McLean
Joined: 2009-11-11,
User offline. Last seen 2 years 48 weeks ago.
Re: Scaladoc that is actually useful?

By whose definition of "confusing"? I think that expanding the
documentation significantly would pay a handsome dividend in
understand by newbies that would lead to greater acceptance of the
language.

Elitist snobbery sure as heck isn't going to get the job done.

On Fri, Nov 13, 2009 at 3:03 PM, Bastian, Mark wrote:
>
> Regarding the debate, my suggestion would be to concisely document that
> which is confusing and let the method signatures be the docs where no
> confusion exists. Crazy talk, I know.

Dave Griffith
Joined: 2009-01-14,
User offline. Last seen 42 years 45 weeks ago.
Re: Scaladoc that is actually useful?

Donald McLean-3 wrote:
>
> Elitist snobbery sure as heck isn't going to get the job done.
>

Presumably it makes them happier. I'd hate to think they were doing it
without getting some joy out of it.

--Dave Griffith

Bastian, Mark
Joined: 2009-01-16,
User offline. Last seen 42 years 45 weeks ago.
Re: Scaladoc that is actually useful?
Re: [scala-user] Scaladoc that is actually useful? Although my statement is certainly subjective, I think most programmers could look at an API they are developing and determine what might be a bit confusing to the unwashed masses and what is mostly self-explanatory.

For example (assuming this is a collection-type class):
def add(item : T) //not confusing
def +(item : T) //Not confusing
def boo[A, B, C](f: A => B, g: B => C): A => C //Potentially confusing

As a member of the unwashed masses, I wouldn’t mind an explanation of what boo does.

-Mark

On 11/13/09 1:18 PM, "Donald McLean" <dmclean62 [at] gmail [dot] com" rel="nofollow">dmclean62 [at] gmail [dot] com> wrote:

By whose definition of "confusing"? I think that expanding the
documentation significantly would pay a handsome dividend in
understand by newbies that would lead to greater acceptance of the
language.

Elitist snobbery sure as heck isn't going to get the job done.

On Fri, Nov 13, 2009 at 3:03 PM, Bastian, Mark <mbastia [at] sandia [dot] gov" rel="nofollow">mbastia [at] sandia [dot] gov> wrote:
>
> Regarding the debate, my suggestion would be to concisely document that
> which is confusing and let the method signatures be the docs where no
> confusion exists. Crazy talk, I know.
--
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


ebowman
Joined: 2009-04-13,
User offline. Last seen 1 year 30 weeks ago.
Re: Scaladoc that is actually useful?

The level of quality and detail of the ScalaTest scaladocs sets a nice
standard here.

Donald McLean wrote:
> By whose definition of "confusing"? I think that expanding the
> documentation significantly would pay a handsome dividend in
> understand by newbies that would lead to greater acceptance of the
> language.
>
> Elitist snobbery sure as heck isn't going to get the job done.
>
> On Fri, Nov 13, 2009 at 3:03 PM, Bastian, Mark wrote:
>
>> Regarding the debate, my suggestion would be to concisely document that
>> which is confusing and let the method signatures be the docs where no
>> confusion exists. Crazy talk, I know.
>>

pchapin
Joined: 2009-01-18,
User offline. Last seen 3 years 12 weeks ago.
Re: Scaladoc that is actually useful?

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"

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.

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 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.

Peter

pchapin
Joined: 2009-01-18,
User offline. Last seen 3 years 12 weeks ago.
Re: Scaladoc that is actually useful?

Randall R Schulz wrote in
news:200911130927 [dot] 01331 [dot] rschulz [at] sonic [dot] net:

> On Friday November 13 2009, Meredith Gregory wrote:
>> Dear Tony,
>>
>> ... However, there is an implicit position in your argumentation here
>> that is a little troubling. The position is that there is no
>> interesting or useful information between type and implementation
>> that can be conveyed without redundancy or without revealing
>> implementation details that should remain hidden. ...
>
> I'm pretty sure the particular case of composing two arbitrary functions
> was just one example that Tony chose specifically 'cause it is simple
> enough to exhibit the property that the type signature alone fully
> constrains what a truly conforming method can compute.

Are you suggesting that there can only be one function taking f : A=>B and
g : B=>C, returning A=>C? What about side effects?

Peter

Randall R Schulz
Joined: 2008-12-16,
User offline. Last seen 1 year 29 weeks ago.
Re: Re: Scaladoc that is actually useful?

On Sunday November 15 2009, Peter C. Chapin wrote:
> Randall R Schulz wrote:
> > On Friday November 13 2009, Meredith Gregory wrote:
> >> Dear Tony,
> >>
> >> ... However, there is an implicit position in your argumentation
> >> here that is a little troubling. The position is that there is no
> >> interesting or useful information between type and implementation
> >> that can be conveyed without redundancy or without revealing
> >> implementation details that should remain hidden. ...
> >
> > I'm pretty sure the particular case of composing two arbitrary
> > functions was just one example that Tony chose specifically 'cause
> > it is simple enough to exhibit the property that the type signature
> > alone fully constrains what a truly conforming method can compute.
>
> Are you suggesting that there can only be one function taking f :
> A=>B and g : B=>C, returning A=>C? What about side effects?

Functions don't have side effects. And they're referentially
transparent. Hence, as Tony has repeatedly stated, absent one sort of
lie or another in that code (w.r.t. the signature) that type signature
is "occupied by" only one function.

By the way, my own code is absolutely lousy with type lies. I'm only
representing the pure functional perspective, and not trying to portray
myself as functionally purer than thou. I do strongly believe that
understanding the foundations of computing, which is what this is
about, is critical for our profession, even if you're going to flout
the rules when it serves your purpose (what Tony would, I think, call
the evil of pragmatism).

> Peter

Randall Schulz

Randall R Schulz
Joined: 2008-12-16,
User offline. Last seen 1 year 29 weeks ago.
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

Meredith Gregory
Joined: 2008-12-17,
User offline. Last seen 42 years 45 weeks ago.
Re: Re: Scaladoc that is actually useful?
Dear Randall,

For each k in the Naturals we have
Compose( k )( f, g )( x ) = { val d = computeKthDigitOfPi( k ); g( f( x ) ) }
The type is inhabited by a countably infinite set of inhabitants. If your observation set includes running time (note my previous point about complexity in my previous comment on this), then these are distinguishable from each other. For many people running time and other forms of complexity (such as space consumption) are practically useful distinguishing characteristics of implementations, aka inhabitants of a type.

Furthermore, you have failed to consider convolution as a critically and practically important example of how to combine two functions. As i have said before useful type systems do not, and should not, nail down implementation. This leaves room for documentation to fill in some of the gaps.

Best wishes,

--greg

On Sun, Nov 15, 2009 at 7:53 AM, Randall R Schulz <rschulz [at] sonic [dot] net> wrote:
On Sunday November 15 2009, Peter C. Chapin wrote:
> Randall R Schulz <rschulz [at] sonic [dot] net> wrote:
> > On Friday November 13 2009, Meredith Gregory wrote:
> >> Dear Tony,
> >>
> >> ... However, there is an implicit position in your argumentation
> >> here that is a little troubling. The position is that there is no
> >> interesting or useful information between type and implementation
> >> that can be conveyed without redundancy or without revealing
> >> implementation details that should remain hidden. ...
> >
> > I'm pretty sure the particular case of composing two arbitrary
> > functions was just one example that Tony chose specifically 'cause
> > it is simple enough to exhibit the property that the type signature
> > alone fully constrains what a truly conforming method can compute.
>
> Are you suggesting that there can only be one function taking f :
> A=>B and g : B=>C, returning A=>C? What about side effects?

Functions don't have side effects. And they're referentially
transparent. Hence, as Tony has repeatedly stated, absent one sort of
lie or another in that code (w.r.t. the signature) that type signature
is "occupied by" only one function.


By the way, my own code is absolutely lousy with type lies. I'm only
representing the pure functional perspective, and not trying to portray
myself as functionally purer than thou. I do strongly believe that
understanding the foundations of computing, which is what this is
about, is critical for our profession, even if you're going to flout
the rules when it serves your purpose (what Tony would, I think, call
the evil of pragmatism).


> Peter


Randall Schulz



--
L.G. Meredith
Managing Partner
Biosimilarity LLC
1219 NW 83rd St
Seattle, WA 98117

+1 206.650.3740

http://biosimilarity.blogspot.com
Ricky Clarkson
Joined: 2008-12-19,
User offline. Last seen 3 years 2 weeks ago.
Re: Re: Scaladoc that is actually useful?

>> 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"
>
> How do you know it does that?

Because that's the simplest useful interpretation possible given the
signature. You could assume it returns null, fires missiles or eats
porridge forever, but there's nothing in the signature to suggest
that, so you may as well use the information in the signature to
understand the method.

Haven't you ever failed to understand the name of a method but
understood its signature? Or ever scanned through some docs and found
yourself looking at the return types more than the method names?

As an aside, there's a module, djinn, for a Haskell IRC bot,
lambdabot. It can, given a type for a function, concoct an
implementation:

@djinn (a -> b) -> (b -> c) -> a -> c
f a b c = b (a c)

Many programmers can do the same. Types are useful!

> 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 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.

Where possible, the function should be simple and obvious, and types
should be sufficient to describe it. As I said in another post, I
agree with Tony, except that a good English description is required
wherever one departs from the simple, obvious implementation.

>
> Peter
>
>

Donald McLean
Joined: 2009-11-11,
User offline. Last seen 2 years 48 weeks ago.
Re: Re: Scaladoc that is actually useful?

While there seems to be a strong "let us not pander to the morons"
faction, please keep in mind that many of the people that you are so
casually dismissing do have real power to prevent the adoption of
Scala in their organizations. Failure to provide Scaladoc that is
genuinely useful to people like me who are reasonably bright and
competent developers but not strong theorists is a potentially fatal
mistake. The Scala community will not, in many cases, get a second
chance to prove that their product is NOT a toy dreamed up by
insufferable academic elitists.

On Mon, Nov 16, 2009 at 8:27 AM, Ricky Clarkson
wrote:
>> 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 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.
>
> Where possible, the function should be simple and obvious, and types
> should be sufficient to describe it.  As I said in another post, I
> agree with Tony, except that a good English description is required
> wherever one departs from the simple, obvious implementation.

Ricky Clarkson
Joined: 2008-12-19,
User offline. Last seen 3 years 2 weeks ago.
Re: Re: Scaladoc that is actually useful?

I put it to you that my wife, who has never[1] programmed in her life,
will be able to tell what the signature we have been discussing means.
She might need it rephrasing, as she's not familiar with Scala's
syntax. Here's how I might rephrase it:

There's a converter called f. It takes in a value of type A, and
returns a value of type B.
There's a converter called g. It takes in a value of type B, and
returns a value of type C.

If I have f and g, and a value of type A, how would I get a value of type C?

We might draw boxes on paper too, I don't know yet.

I don't mind pandering to morons, to use your terms, not least as I am
one in many contexts. I'm not dismissing anyone. I see no harm in
documenting signatures, even obvious ones, but I don't see it as
necessary. It's ok to me if Scala cannot be used in organisations
that place so much emphasis on documenting obvious things, rather than
having their staff understand fundamental concepts. Note that I'm not
even a committer though, and neither is Tony, to my knowledge. If
you're unhappy with the documentation, I've never heard of a
documentation-adding patch being rejected.

[1] I got her doing a little bit of Scheme a couple of years ago, just
to keep her awake in a boring job. She picked Ruby after I showed her
code snippets from 13 languages, so she'll be learning that (as will
I) soon.

2009/11/16 Donald McLean :
> While there seems to be a strong "let us not pander to the morons"
> faction, please keep in mind that many of the people that you are so
> casually dismissing do have real power to prevent the adoption of
> Scala in their organizations. Failure to provide Scaladoc that is
> genuinely useful to people like me who are reasonably bright and
> competent developers but not strong theorists is a potentially fatal
> mistake. The Scala community will not, in many cases, get a second
> chance to prove that their product is NOT a toy dreamed up by
> insufferable academic elitists.
>
> On Mon, Nov 16, 2009 at 8:27 AM, Ricky Clarkson
> wrote:
>>> 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 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.
>>
>> Where possible, the function should be simple and obvious, and types
>> should be sufficient to describe it.  As I said in another post, I
>> agree with Tony, except that a good English description is required
>> wherever one departs from the simple, obvious implementation.
> --
> 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
>

nilskp
Joined: 2009-01-30,
User offline. Last seen 1 year 27 weeks ago.
Re: Re: Scaladoc that is actually useful?
On Mon, Nov 16, 2009 at 8:24 AM, Donald McLean <dmclean62 [at] gmail [dot] com> wrote:
While there seems to be a strong "let us not pander to the morons"
faction, please keep in mind that many of the people that you are so
casually dismissing do have real power to prevent the adoption of
Scala in their organizations.

I suspect that that faction could not care less about Scala's rate of adoption. In fact, I get the impression some might see high adoption rates as a negative.

(Side note: double "that", as written above, has to be one of the ugliest constructs in the English language)
Meredith Gregory
Joined: 2008-12-17,
User offline. Last seen 42 years 45 weeks ago.
Re: Re: Scaladoc that is actually useful?
Dear Ricky,

i have responded to this argument repeatedly. i'm not sure why people are not getting this. Tony's argument is blatantly false. There are countably infinitely many inhabitants of the type (A => B) => (B => C) => A => C. They are observably distinguished by running time and space consumption. Here is one infinite subset of that set: for each k in the natural numbers we have

Compose_k( f, g ) = { ( x ) => { var d = computeKthDigitOfPi( k ); g( f( x ) ) } : (A => B) => (B => C) => A => C

There are lots more infinite subsets where that one came from. The differences in complexity are not just manifest by silliness of the kind above. There are materially relevant differences that have to do with the internal representation of function and evaluation.

Beyond that, consider the following function

// provided A, B, C <: T with T supporting a certain algebraic structure
Convolution_tau( f, g ) = { ( t ) => { integrate( f( t ) * g( tau - t ), posInf, negInf ) } } : (A => B) => (B => C) => A => C

For the subset of types supporting a certain algebraic structure -- i.e. we restrict the universe of quantification in the original theorem -- this is a useful example of a way of getting functions from pairs of functions that is not a composition. Convolution is a useful notion that arises in physical sciences as well as in computation. 

The important point in all of this is that Scala's type system doesn't see certain aspects of computation that are still materially relevant to working programmers. The stuff that falls into this category can make practically useful documentation.

Best wishes,

--greg

On Mon, Nov 16, 2009 at 6:53 AM, Ricky Clarkson <ricky [dot] clarkson [at] gmail [dot] com> wrote:
I put it to you that my wife, who has never[1] programmed in her life,
will be able to tell what the signature we have been discussing means.
 She might need it rephrasing, as she's not familiar with Scala's
syntax.  Here's how I might rephrase it:

There's a converter called f.  It takes in a value of type A, and
returns a value of type B.
There's a converter called g.  It takes in a value of type B, and
returns a value of type C.

If I have f and g, and a value of type A, how would I get a value of type C?

We might draw boxes on paper too, I don't know yet.

I don't mind pandering to morons, to use your terms, not least as I am
one in many contexts.  I'm not dismissing anyone.  I see no harm in
documenting signatures, even obvious ones, but I don't see it as
necessary.  It's ok to me if Scala cannot be used in organisations
that place so much emphasis on documenting obvious things, rather than
having their staff understand fundamental concepts.  Note that I'm not
even a committer though, and neither is Tony, to my knowledge.  If
you're unhappy with the documentation, I've never heard of a
documentation-adding patch being rejected.

[1] I got her doing a little bit of Scheme a couple of years ago, just
to keep her awake in a boring job.  She picked Ruby after I showed her
code snippets from 13 languages, so she'll be learning that (as will
I) soon.

2009/11/16 Donald McLean <dmclean62 [at] gmail [dot] com>:
> While there seems to be a strong "let us not pander to the morons"
> faction, please keep in mind that many of the people that you are so
> casually dismissing do have real power to prevent the adoption of
> Scala in their organizations. Failure to provide Scaladoc that is
> genuinely useful to people like me who are reasonably bright and
> competent developers but not strong theorists is a potentially fatal
> mistake. The Scala community will not, in many cases, get a second
> chance to prove that their product is NOT a toy dreamed up by
> insufferable academic elitists.
>
> On Mon, Nov 16, 2009 at 8:27 AM, Ricky Clarkson
> <ricky [dot] clarkson [at] gmail [dot] com> wrote:
>>> 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 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.
>>
>> Where possible, the function should be simple and obvious, and types
>> should be sufficient to describe it.  As I said in another post, I
>> agree with Tony, except that a good English description is required
>> wherever one departs from the simple, obvious implementation.
> --
> 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
>



--
Ricky Clarkson
Java and Scala Programmer, AD Holdings
+44 1565 770804
Skype: ricky_clarkson
Google Talk: ricky [dot] clarkson [at] gmail [dot] com
Google Wave: ricky [dot] clarkson [at] googlewave [dot] com



--
L.G. Meredith
Managing Partner
Biosimilarity LLC
1219 NW 83rd St
Seattle, WA 98117

+1 206.650.3740

http://biosimilarity.blogspot.com
Ricky Clarkson
Joined: 2008-12-19,
User offline. Last seen 3 years 2 weeks ago.
Re: Re: Scaladoc that is actually useful?

Hi Meredith,

Moved to scala-debate.

Am I correct that there is only one *function* that inhabits that
signature? There may be many procedures that you can perform, but
looking at the input types and return type, and assuming there's no
null, is there another function that the procedure could compute?

Ricky.

2009/11/16 Meredith Gregory :
> Dear Ricky,
>
> i have responded to this argument repeatedly. i'm not sure why people are
> not getting this. Tony's argument is blatantly false. There are countably
> infinitely many inhabitants of the type (A => B) => (B => C) => A => C. They
> are observably distinguished by running time and space consumption. Here is
> one infinite subset of that set: for each k in the natural numbers we have
>
> Compose_k( f, g ) = { ( x ) => { var d = computeKthDigitOfPi( k ); g( f( x )
> ) } : (A => B) => (B => C) => A => C
>
> There are lots more infinite subsets where that one came from. The
> differences in complexity are not just manifest by silliness of the kind
> above. There are materially relevant differences that have to do with the
> internal representation of function and evaluation.
>
> Beyond that, consider the following function
>
> // provided A, B, C <: T with T supporting a certain algebraic structure
> Convolution_tau( f, g ) = { ( t ) => { integrate( f( t ) * g( tau - t ),
> posInf, negInf ) } } : (A => B) => (B => C) => A => C
>
> For the subset of types supporting a certain algebraic structure -- i.e. we
> restrict the universe of quantification in the original theorem -- this is a
> useful example of a way of getting functions from pairs of functions that is
> not a composition. Convolution is a useful notion that arises in physical
> sciences as well as in computation.
>
> The important point in all of this is that Scala's type system doesn't see
> certain aspects of computation that are still materially relevant to working
> programmers. The stuff that falls into this category can make practically
> useful documentation.
>
> Best wishes,
>
> --greg
>
> On Mon, Nov 16, 2009 at 6:53 AM, Ricky Clarkson
> wrote:
>>
>> I put it to you that my wife, who has never[1] programmed in her life,
>> will be able to tell what the signature we have been discussing means.
>>  She might need it rephrasing, as she's not familiar with Scala's
>> syntax.  Here's how I might rephrase it:
>>
>> There's a converter called f.  It takes in a value of type A, and
>> returns a value of type B.
>> There's a converter called g.  It takes in a value of type B, and
>> returns a value of type C.
>>
>> If I have f and g, and a value of type A, how would I get a value of type
>> C?
>>
>> We might draw boxes on paper too, I don't know yet.
>>
>> I don't mind pandering to morons, to use your terms, not least as I am
>> one in many contexts.  I'm not dismissing anyone.  I see no harm in
>> documenting signatures, even obvious ones, but I don't see it as
>> necessary.  It's ok to me if Scala cannot be used in organisations
>> that place so much emphasis on documenting obvious things, rather than
>> having their staff understand fundamental concepts.  Note that I'm not
>> even a committer though, and neither is Tony, to my knowledge.  If
>> you're unhappy with the documentation, I've never heard of a
>> documentation-adding patch being rejected.
>>
>> [1] I got her doing a little bit of Scheme a couple of years ago, just
>> to keep her awake in a boring job.  She picked Ruby after I showed her
>> code snippets from 13 languages, so she'll be learning that (as will
>> I) soon.
>>
>> 2009/11/16 Donald McLean :
>> > While there seems to be a strong "let us not pander to the morons"
>> > faction, please keep in mind that many of the people that you are so
>> > casually dismissing do have real power to prevent the adoption of
>> > Scala in their organizations. Failure to provide Scaladoc that is
>> > genuinely useful to people like me who are reasonably bright and
>> > competent developers but not strong theorists is a potentially fatal
>> > mistake. The Scala community will not, in many cases, get a second
>> > chance to prove that their product is NOT a toy dreamed up by
>> > insufferable academic elitists.
>> >
>> > On Mon, Nov 16, 2009 at 8:27 AM, Ricky Clarkson
>> > wrote:
>> >>> 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 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.
>> >>
>> >> Where possible, the function should be simple and obvious, and types
>> >> should be sufficient to describe it.  As I said in another post, I
>> >> agree with Tony, except that a good English description is required
>> >> wherever one departs from the simple, obvious implementation.
>> > --
>> > 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
>> >
>>
>>
>>
>> --
>> Ricky Clarkson
>> Java and Scala Programmer, AD Holdings
>> +44 1565 770804
>> Skype: ricky_clarkson
>> Google Talk: ricky [dot] clarkson [at] gmail [dot] com
>> Google Wave: ricky [dot] clarkson [at] googlewave [dot] com
>
>
>
> --
> L.G. Meredith
> Managing Partner
> Biosimilarity LLC
> 1219 NW 83rd St
> Seattle, WA 98117
>
> +1 206.650.3740
>
> http://biosimilarity.blogspot.com
>

Meredith Gregory
Joined: 2008-12-17,
User offline. Last seen 42 years 45 weeks ago.
Re: Re: Scaladoc that is actually useful?
Dear Ricky,

i think i just gave the Scala code for an infinite subset of the countably infinite set of functions that inhabit that type.

Best wishes,

--greg

On Mon, Nov 16, 2009 at 8:44 AM, Ricky Clarkson <ricky [dot] clarkson [at] gmail [dot] com> wrote:
Hi Meredith,

Moved to scala-debate.

Am I correct that there is only one *function* that inhabits that
signature?  There may be many procedures that you can perform, but
looking at the input types and return type, and assuming there's no
null, is there another function that the procedure could compute?

Ricky.

2009/11/16 Meredith Gregory <lgreg [dot] meredith [at] gmail [dot] com>:
> Dear Ricky,
>
> i have responded to this argument repeatedly. i'm not sure why people are
> not getting this. Tony's argument is blatantly false. There are countably
> infinitely many inhabitants of the type (A => B) => (B => C) => A => C. They
> are observably distinguished by running time and space consumption. Here is
> one infinite subset of that set: for each k in the natural numbers we have
>
> Compose_k( f, g ) = { ( x ) => { var d = computeKthDigitOfPi( k ); g( f( x )
> ) } : (A => B) => (B => C) => A => C
>
> There are lots more infinite subsets where that one came from. The
> differences in complexity are not just manifest by silliness of the kind
> above. There are materially relevant differences that have to do with the
> internal representation of function and evaluation.
>
> Beyond that, consider the following function
>
> // provided A, B, C <: T with T supporting a certain algebraic structure
> Convolution_tau( f, g ) = { ( t ) => { integrate( f( t ) * g( tau - t ),
> posInf, negInf ) } } : (A => B) => (B => C) => A => C
>
> For the subset of types supporting a certain algebraic structure -- i.e. we
> restrict the universe of quantification in the original theorem -- this is a
> useful example of a way of getting functions from pairs of functions that is
> not a composition. Convolution is a useful notion that arises in physical
> sciences as well as in computation.
>
> The important point in all of this is that Scala's type system doesn't see
> certain aspects of computation that are still materially relevant to working
> programmers. The stuff that falls into this category can make practically
> useful documentation.
>
> Best wishes,
>
> --greg
>
> On Mon, Nov 16, 2009 at 6:53 AM, Ricky Clarkson <ricky [dot] clarkson [at] gmail [dot] com>
> wrote:
>>
>> I put it to you that my wife, who has never[1] programmed in her life,
>> will be able to tell what the signature we have been discussing means.
>>  She might need it rephrasing, as she's not familiar with Scala's
>> syntax.  Here's how I might rephrase it:
>>
>> There's a converter called f.  It takes in a value of type A, and
>> returns a value of type B.
>> There's a converter called g.  It takes in a value of type B, and
>> returns a value of type C.
>>
>> If I have f and g, and a value of type A, how would I get a value of type
>> C?
>>
>> We might draw boxes on paper too, I don't know yet.
>>
>> I don't mind pandering to morons, to use your terms, not least as I am
>> one in many contexts.  I'm not dismissing anyone.  I see no harm in
>> documenting signatures, even obvious ones, but I don't see it as
>> necessary.  It's ok to me if Scala cannot be used in organisations
>> that place so much emphasis on documenting obvious things, rather than
>> having their staff understand fundamental concepts.  Note that I'm not
>> even a committer though, and neither is Tony, to my knowledge.  If
>> you're unhappy with the documentation, I've never heard of a
>> documentation-adding patch being rejected.
>>
>> [1] I got her doing a little bit of Scheme a couple of years ago, just
>> to keep her awake in a boring job.  She picked Ruby after I showed her
>> code snippets from 13 languages, so she'll be learning that (as will
>> I) soon.
>>
>> 2009/11/16 Donald McLean <dmclean62 [at] gmail [dot] com>:
>> > While there seems to be a strong "let us not pander to the morons"
>> > faction, please keep in mind that many of the people that you are so
>> > casually dismissing do have real power to prevent the adoption of
>> > Scala in their organizations. Failure to provide Scaladoc that is
>> > genuinely useful to people like me who are reasonably bright and
>> > competent developers but not strong theorists is a potentially fatal
>> > mistake. The Scala community will not, in many cases, get a second
>> > chance to prove that their product is NOT a toy dreamed up by
>> > insufferable academic elitists.
>> >
>> > On Mon, Nov 16, 2009 at 8:27 AM, Ricky Clarkson
>> > <ricky [dot] clarkson [at] gmail [dot] com> wrote:
>> >>> 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 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.
>> >>
>> >> Where possible, the function should be simple and obvious, and types
>> >> should be sufficient to describe it.  As I said in another post, I
>> >> agree with Tony, except that a good English description is required
>> >> wherever one departs from the simple, obvious implementation.
>> > --
>> > 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
>> >
>>
>>
>>
>> --
>> Ricky Clarkson
>> Java and Scala Programmer, AD Holdings
>> +44 1565 770804
>> Skype: ricky_clarkson
>> Google Talk: ricky [dot] clarkson [at] gmail [dot] com
>> Google Wave: ricky [dot] clarkson [at] googlewave [dot] com
>
>
>
> --
> L.G. Meredith
> Managing Partner
> Biosimilarity LLC
> 1219 NW 83rd St
> Seattle, WA 98117
>
> +1 206.650.3740
>
> http://biosimilarity.blogspot.com
>



--
Ricky Clarkson
Java and Scala Programmer, AD Holdings
+44 1565 770804
Skype: ricky_clarkson
Google Talk: ricky [dot] clarkson [at] gmail [dot] com
Google Wave: ricky [dot] clarkson [at] googlewave [dot] com



--
L.G. Meredith
Managing Partner
Biosimilarity LLC
1219 NW 83rd St
Seattle, WA 98117

+1 206.650.3740

http://biosimilarity.blogspot.com
Ricky Clarkson
Joined: 2008-12-19,
User offline. Last seen 3 years 2 weeks ago.
Re: Re: Scaladoc that is actually useful?

Meredith,

I don't think so, given that one defines a function as I do, something
that takes in arguments and returns values. If you're interested in
what it *does*, you're interested in a procedure, not a function,
according to the definitions I learned in high school.

Ricky.

2009/11/16 Meredith Gregory :
> Dear Ricky,
>
> i think i just gave the Scala code for an infinite subset of the countably
> infinite set of functions that inhabit that type.
>
> Best wishes,
>
> --greg
>
> On Mon, Nov 16, 2009 at 8:44 AM, Ricky Clarkson
> wrote:
>>
>> Hi Meredith,
>>
>> Moved to scala-debate.
>>
>> Am I correct that there is only one *function* that inhabits that
>> signature?  There may be many procedures that you can perform, but
>> looking at the input types and return type, and assuming there's no
>> null, is there another function that the procedure could compute?
>>
>> Ricky.
>>
>> 2009/11/16 Meredith Gregory :
>> > Dear Ricky,
>> >
>> > i have responded to this argument repeatedly. i'm not sure why people
>> > are
>> > not getting this. Tony's argument is blatantly false. There are
>> > countably
>> > infinitely many inhabitants of the type (A => B) => (B => C) => A => C.
>> > They
>> > are observably distinguished by running time and space consumption. Here
>> > is
>> > one infinite subset of that set: for each k in the natural numbers we
>> > have
>> >
>> > Compose_k( f, g ) = { ( x ) => { var d = computeKthDigitOfPi( k ); g( f(
>> > x )
>> > ) } : (A => B) => (B => C) => A => C
>> >
>> > There are lots more infinite subsets where that one came from. The
>> > differences in complexity are not just manifest by silliness of the kind
>> > above. There are materially relevant differences that have to do with
>> > the
>> > internal representation of function and evaluation.
>> >
>> > Beyond that, consider the following function
>> >
>> > // provided A, B, C <: T with T supporting a certain algebraic structure
>> > Convolution_tau( f, g ) = { ( t ) => { integrate( f( t ) * g( tau - t ),
>> > posInf, negInf ) } } : (A => B) => (B => C) => A => C
>> >
>> > For the subset of types supporting a certain algebraic structure -- i.e.
>> > we
>> > restrict the universe of quantification in the original theorem -- this
>> > is a
>> > useful example of a way of getting functions from pairs of functions
>> > that is
>> > not a composition. Convolution is a useful notion that arises in
>> > physical
>> > sciences as well as in computation.
>> >
>> > The important point in all of this is that Scala's type system doesn't
>> > see
>> > certain aspects of computation that are still materially relevant to
>> > working
>> > programmers. The stuff that falls into this category can make
>> > practically
>> > useful documentation.
>> >
>> > Best wishes,
>> >
>> > --greg
>> >
>> > On Mon, Nov 16, 2009 at 6:53 AM, Ricky Clarkson
>> >
>> > wrote:
>> >>
>> >> I put it to you that my wife, who has never[1] programmed in her life,
>> >> will be able to tell what the signature we have been discussing means.
>> >>  She might need it rephrasing, as she's not familiar with Scala's
>> >> syntax.  Here's how I might rephrase it:
>> >>
>> >> There's a converter called f.  It takes in a value of type A, and
>> >> returns a value of type B.
>> >> There's a converter called g.  It takes in a value of type B, and
>> >> returns a value of type C.
>> >>
>> >> If I have f and g, and a value of type A, how would I get a value of
>> >> type
>> >> C?
>> >>
>> >> We might draw boxes on paper too, I don't know yet.
>> >>
>> >> I don't mind pandering to morons, to use your terms, not least as I am
>> >> one in many contexts.  I'm not dismissing anyone.  I see no harm in
>> >> documenting signatures, even obvious ones, but I don't see it as
>> >> necessary.  It's ok to me if Scala cannot be used in organisations
>> >> that place so much emphasis on documenting obvious things, rather than
>> >> having their staff understand fundamental concepts.  Note that I'm not
>> >> even a committer though, and neither is Tony, to my knowledge.  If
>> >> you're unhappy with the documentation, I've never heard of a
>> >> documentation-adding patch being rejected.
>> >>
>> >> [1] I got her doing a little bit of Scheme a couple of years ago, just
>> >> to keep her awake in a boring job.  She picked Ruby after I showed her
>> >> code snippets from 13 languages, so she'll be learning that (as will
>> >> I) soon.
>> >>
>> >> 2009/11/16 Donald McLean :
>> >> > While there seems to be a strong "let us not pander to the morons"
>> >> > faction, please keep in mind that many of the people that you are so
>> >> > casually dismissing do have real power to prevent the adoption of
>> >> > Scala in their organizations. Failure to provide Scaladoc that is
>> >> > genuinely useful to people like me who are reasonably bright and
>> >> > competent developers but not strong theorists is a potentially fatal
>> >> > mistake. The Scala community will not, in many cases, get a second
>> >> > chance to prove that their product is NOT a toy dreamed up by
>> >> > insufferable academic elitists.
>> >> >
>> >> > On Mon, Nov 16, 2009 at 8:27 AM, Ricky Clarkson
>> >> > wrote:
>> >> >>> 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 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.
>> >> >>
>> >> >> Where possible, the function should be simple and obvious, and types
>> >> >> should be sufficient to describe it.  As I said in another post, I
>> >> >> agree with Tony, except that a good English description is required
>> >> >> wherever one departs from the simple, obvious implementation.
>> >> > --
>> >> > 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
>> >> >
>> >>
>> >>
>> >>
>> >> --
>> >> Ricky Clarkson
>> >> Java and Scala Programmer, AD Holdings
>> >> +44 1565 770804
>> >> Skype: ricky_clarkson
>> >> Google Talk: ricky [dot] clarkson [at] gmail [dot] com
>> >> Google Wave: ricky [dot] clarkson [at] googlewave [dot] com
>> >
>> >
>> >
>> > --
>> > L.G. Meredith
>> > Managing Partner
>> > Biosimilarity LLC
>> > 1219 NW 83rd St
>> > Seattle, WA 98117
>> >
>> > +1 206.650.3740
>> >
>> > http://biosimilarity.blogspot.com
>> >
>>
>>
>>
>> --
>> Ricky Clarkson
>> Java and Scala Programmer, AD Holdings
>> +44 1565 770804
>> Skype: ricky_clarkson
>> Google Talk: ricky [dot] clarkson [at] gmail [dot] com
>> Google Wave: ricky [dot] clarkson [at] googlewave [dot] com
>
>
>
> --
> L.G. Meredith
> Managing Partner
> Biosimilarity LLC
> 1219 NW 83rd St
> Seattle, WA 98117
>
> +1 206.650.3740
>
> http://biosimilarity.blogspot.com
>

Johannes Rudolph
Joined: 2008-12-17,
User offline. Last seen 29 weeks 20 hours ago.
Re: Re: Scaladoc that is actually useful?

On Mon, Nov 16, 2009 at 6:09 PM, Ricky Clarkson
wrote:
> Meredith,
>
> I don't think so, given that one defines a function as I do, something
> that takes in arguments and returns values.  If you're interested in
> what it *does*, you're interested in a procedure, not a function,
> according to the definitions I learned in high school.

How about keeping that discussion at least a bit in context? We are
talking about functions in Scala and most of us are using programming
languages to run programs on real machines. Real machines calculate
results normally by use of side-effects (space / time). So we never
deal with real pure functions in the mathematic sense if we speak
about real runnable programs. So a description of the time/space
complexity of an algorithm to run on a real machine needs some
specification about it's runtime behaviour.

Bradley Buchsbaum
Joined: 2009-04-15,
User offline. Last seen 42 years 45 weeks ago.
Re: Re: Scaladoc that is actually useful?
The good news is that we've narrowed it down a bit: there's either one or a countably infinite number of inhabitants of the function.  (If the latter, then I can only hope they're all happy.)





On Mon, Nov 16, 2009 at 12:17 PM, Johannes Rudolph <johannes [dot] rudolph [at] googlemail [dot] com> wrote:
On Mon, Nov 16, 2009 at 6:09 PM, Ricky Clarkson
<ricky [dot] clarkson [at] gmail [dot] com> wrote:
> Meredith,
>
> I don't think so, given that one defines a function as I do, something
> that takes in arguments and returns values.  If you're interested in
> what it *does*, you're interested in a procedure, not a function,
> according to the definitions I learned in high school.

How about keeping that discussion at least a bit in context? We are
talking about functions in Scala and most of us are using programming
languages to run programs on real machines. Real machines calculate
results normally by use of side-effects (space / time). So we never
deal with real pure functions in the mathematic sense if we speak
about real runnable programs. So a description of the time/space
complexity of an algorithm to run on a real machine needs some
specification about it's runtime behaviour.

--
Johannes

-----------------------------------------------
Johannes Rudolph
http://virtual-void.net



--
Bradley R. Buchsbaum
Rotman Research Institute
3560 Bathurst St.
Toronto, ON Canada M6A 2E1
email: bbuchsbaum [at] rotman-baycrest [dot] on [dot] ca
Meredith Gregory
Joined: 2008-12-17,
User offline. Last seen 42 years 45 weeks ago.
Re: Re: Scaladoc that is actually useful?
Dear Ricky,
Thanks for your note. Here are some of the notions of function with which i have some familiarity 
  • lambda calculus
  • recursive function theory
  • set theoretic
  • category theoretic
All of these notions are consistent with my definitions and examples. Could you provide me your definition as it is fresh and may result in an insight for me?
Best wishes,
--greg

On Mon, Nov 16, 2009 at 9:09 AM, Ricky Clarkson <ricky [dot] clarkson [at] gmail [dot] com> wrote:
Meredith,

I don't think so, given that one defines a function as I do, something
that takes in arguments and returns values.  If you're interested in
what it *does*, you're interested in a procedure, not a function,
according to the definitions I learned in high school.

Ricky.

2009/11/16 Meredith Gregory <lgreg [dot] meredith [at] gmail [dot] com>:
> Dear Ricky,
>
> i think i just gave the Scala code for an infinite subset of the countably
> infinite set of functions that inhabit that type.
>
> Best wishes,
>
> --greg
>
> On Mon, Nov 16, 2009 at 8:44 AM, Ricky Clarkson <ricky [dot] clarkson [at] gmail [dot] com>
> wrote:
>>
>> Hi Meredith,
>>
>> Moved to scala-debate.
>>
>> Am I correct that there is only one *function* that inhabits that
>> signature?  There may be many procedures that you can perform, but
>> looking at the input types and return type, and assuming there's no
>> null, is there another function that the procedure could compute?
>>
>> Ricky.
>>
>> 2009/11/16 Meredith Gregory <lgreg [dot] meredith [at] gmail [dot] com>:
>> > Dear Ricky,
>> >
>> > i have responded to this argument repeatedly. i'm not sure why people
>> > are
>> > not getting this. Tony's argument is blatantly false. There are
>> > countably
>> > infinitely many inhabitants of the type (A => B) => (B => C) => A => C.
>> > They
>> > are observably distinguished by running time and space consumption. Here
>> > is
>> > one infinite subset of that set: for each k in the natural numbers we
>> > have
>> >
>> > Compose_k( f, g ) = { ( x ) => { var d = computeKthDigitOfPi( k ); g( f(
>> > x )
>> > ) } : (A => B) => (B => C) => A => C
>> >
>> > There are lots more infinite subsets where that one came from. The
>> > differences in complexity are not just manifest by silliness of the kind
>> > above. There are materially relevant differences that have to do with
>> > the
>> > internal representation of function and evaluation.
>> >
>> > Beyond that, consider the following function
>> >
>> > // provided A, B, C <: T with T supporting a certain algebraic structure
>> > Convolution_tau( f, g ) = { ( t ) => { integrate( f( t ) * g( tau - t ),
>> > posInf, negInf ) } } : (A => B) => (B => C) => A => C
>> >
>> > For the subset of types supporting a certain algebraic structure -- i.e.
>> > we
>> > restrict the universe of quantification in the original theorem -- this
>> > is a
>> > useful example of a way of getting functions from pairs of functions
>> > that is
>> > not a composition. Convolution is a useful notion that arises in
>> > physical
>> > sciences as well as in computation.
>> >
>> > The important point in all of this is that Scala's type system doesn't
>> > see
>> > certain aspects of computation that are still materially relevant to
>> > working
>> > programmers. The stuff that falls into this category can make
>> > practically
>> > useful documentation.
>> >
>> > Best wishes,
>> >
>> > --greg
>> >
>> > On Mon, Nov 16, 2009 at 6:53 AM, Ricky Clarkson
>> > <ricky [dot] clarkson [at] gmail [dot] com>
>> > wrote:
>> >>
>> >> I put it to you that my wife, who has never[1] programmed in her life,
>> >> will be able to tell what the signature we have been discussing means.
>> >>  She might need it rephrasing, as she's not familiar with Scala's
>> >> syntax.  Here's how I might rephrase it:
>> >>
>> >> There's a converter called f.  It takes in a value of type A, and
>> >> returns a value of type B.
>> >> There's a converter called g.  It takes in a value of type B, and
>> >> returns a value of type C.
>> >>
>> >> If I have f and g, and a value of type A, how would I get a value of
>> >> type
>> >> C?
>> >>
>> >> We might draw boxes on paper too, I don't know yet.
>> >>
>> >> I don't mind pandering to morons, to use your terms, not least as I am
>> >> one in many contexts.  I'm not dismissing anyone.  I see no harm in
>> >> documenting signatures, even obvious ones, but I don't see it as
>> >> necessary.  It's ok to me if Scala cannot be used in organisations
>> >> that place so much emphasis on documenting obvious things, rather than
>> >> having their staff understand fundamental concepts.  Note that I'm not
>> >> even a committer though, and neither is Tony, to my knowledge.  If
>> >> you're unhappy with the documentation, I've never heard of a
>> >> documentation-adding patch being rejected.
>> >>
>> >> [1] I got her doing a little bit of Scheme a couple of years ago, just
>> >> to keep her awake in a boring job.  She picked Ruby after I showed her
>> >> code snippets from 13 languages, so she'll be learning that (as will
>> >> I) soon.
>> >>
>> >> 2009/11/16 Donald McLean <dmclean62 [at] gmail [dot] com>:
>> >> > While there seems to be a strong "let us not pander to the morons"
>> >> > faction, please keep in mind that many of the people that you are so
>> >> > casually dismissing do have real power to prevent the adoption of
>> >> > Scala in their organizations. Failure to provide Scaladoc that is
>> >> > genuinely useful to people like me who are reasonably bright and
>> >> > competent developers but not strong theorists is a potentially fatal
>> >> > mistake. The Scala community will not, in many cases, get a second
>> >> > chance to prove that their product is NOT a toy dreamed up by
>> >> > insufferable academic elitists.
>> >> >
>> >> > On Mon, Nov 16, 2009 at 8:27 AM, Ricky Clarkson
>> >> > <ricky [dot] clarkson [at] gmail [dot] com> wrote:
>> >> >>> 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 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.
>> >> >>
>> >> >> Where possible, the function should be simple and obvious, and types
>> >> >> should be sufficient to describe it.  As I said in another post, I
>> >> >> agree with Tony, except that a good English description is required
>> >> >> wherever one departs from the simple, obvious implementation.
>> >> > --
>> >> > 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
>> >> >
>> >>
>> >>
>> >>
>> >> --
>> >> Ricky Clarkson
>> >> Java and Scala Programmer, AD Holdings
>> >> +44 1565 770804
>> >> Skype: ricky_clarkson
>> >> Google Talk: ricky [dot] clarkson [at] gmail [dot] com
>> >> Google Wave: ricky [dot] clarkson [at] googlewave [dot] com
>> >
>> >
>> >
>> > --
>> > L.G. Meredith
>> > Managing Partner
>> > Biosimilarity LLC
>> > 1219 NW 83rd St
>> > Seattle, WA 98117
>> >
>> > +1 206.650.3740
>> >
>> > http://biosimilarity.blogspot.com
>> >
>>
>>
>>
>> --
>> Ricky Clarkson
>> Java and Scala Programmer, AD Holdings
>> +44 1565 770804
>> Skype: ricky_clarkson
>> Google Talk: ricky [dot] clarkson [at] gmail [dot] com
>> Google Wave: ricky [dot] clarkson [at] googlewave [dot] com
>
>
>
> --
> L.G. Meredith
> Managing Partner
> Biosimilarity LLC
> 1219 NW 83rd St
> Seattle, WA 98117
>
> +1 206.650.3740
>
> http://biosimilarity.blogspot.com
>



--
Ricky Clarkson
Java and Scala Programmer, AD Holdings
+44 1565 770804
Skype: ricky_clarkson
Google Talk: ricky [dot] clarkson [at] gmail [dot] com
Google Wave: ricky [dot] clarkson [at] googlewave [dot] com



--
L.G. Meredith
Managing Partner
Biosimilarity LLC
1219 NW 83rd St
Seattle, WA 98117

+1 206.650.3740

http://biosimilarity.blogspot.com
Ricky Clarkson
Joined: 2008-12-19,
User offline. Last seen 3 years 2 weeks ago.
Re: Re: Scaladoc that is actually useful?

Johannes,

Real machines? Oh, yes, right. So why are you programming in a
language more abstract than assembly? I'd wager that it's because
most if not all the time when programming, it's simpler not to think
in terms of real machines, real registers, real processor-level
caches, etc.

Most of the real problems in real code on real machines that I see in
my real job are because of side effects happening in the wrong order,
not happening or happening too many times. So to me at least, it's
worth thinking about.

Imagine if Math.max was stateful. It'd be hell, you'd have to
remember lock Math before calling max. I don't know why you'd choose
side effects, given a choice between having them and not.

On the topic of what we should talk about, if you don't think it's
worth reading, don't read it.

Ricky.

2009/11/16 Johannes Rudolph :
> On Mon, Nov 16, 2009 at 6:09 PM, Ricky Clarkson
> wrote:
>> Meredith,
>>
>> I don't think so, given that one defines a function as I do, something
>> that takes in arguments and returns values.  If you're interested in
>> what it *does*, you're interested in a procedure, not a function,
>> according to the definitions I learned in high school.
>
> How about keeping that discussion at least a bit in context? We are
> talking about functions in Scala and most of us are using programming
> languages to run programs on real machines. Real machines calculate
> results normally by use of side-effects (space / time). So we never
> deal with real pure functions in the mathematic sense if we speak
> about real runnable programs. So a description of the time/space
> complexity of an algorithm to run on a real machine needs some
> specification about it's runtime behaviour.
>
> --
> Johannes
>
> -----------------------------------------------
> Johannes Rudolph
> http://virtual-void.net
>

Ricky Clarkson
Joined: 2008-12-19,
User offline. Last seen 3 years 2 weeks ago.
Re: Re: Scaladoc that is actually useful?

"(mathematics) a mathematical relation such that each element of a
given set (the domain of the function) is associated with an element
of another"

2009/11/16 Meredith Gregory :
> Dear Ricky,
> Thanks for your note. Here are some of the notions of function with which i
> have some familiarity
>
> lambda calculus
> recursive function theory
> set theoretic
> category theoretic
>
> All of these notions are consistent with my definitions and examples. Could
> you provide me your definition as it is fresh and may result in an insight
> for me?
> Best wishes,
> --greg
>
> On Mon, Nov 16, 2009 at 9:09 AM, Ricky Clarkson
> wrote:
>>
>> Meredith,
>>
>> I don't think so, given that one defines a function as I do, something
>> that takes in arguments and returns values.  If you're interested in
>> what it *does*, you're interested in a procedure, not a function,
>> according to the definitions I learned in high school.
>>
>> Ricky.
>>
>> 2009/11/16 Meredith Gregory :
>> > Dear Ricky,
>> >
>> > i think i just gave the Scala code for an infinite subset of the
>> > countably
>> > infinite set of functions that inhabit that type.
>> >
>> > Best wishes,
>> >
>> > --greg
>> >
>> > On Mon, Nov 16, 2009 at 8:44 AM, Ricky Clarkson
>> >
>> > wrote:
>> >>
>> >> Hi Meredith,
>> >>
>> >> Moved to scala-debate.
>> >>
>> >> Am I correct that there is only one *function* that inhabits that
>> >> signature?  There may be many procedures that you can perform, but
>> >> looking at the input types and return type, and assuming there's no
>> >> null, is there another function that the procedure could compute?
>> >>
>> >> Ricky.
>> >>
>> >> 2009/11/16 Meredith Gregory :
>> >> > Dear Ricky,
>> >> >
>> >> > i have responded to this argument repeatedly. i'm not sure why people
>> >> > are
>> >> > not getting this. Tony's argument is blatantly false. There are
>> >> > countably
>> >> > infinitely many inhabitants of the type (A => B) => (B => C) => A =>
>> >> > C.
>> >> > They
>> >> > are observably distinguished by running time and space consumption.
>> >> > Here
>> >> > is
>> >> > one infinite subset of that set: for each k in the natural numbers we
>> >> > have
>> >> >
>> >> > Compose_k( f, g ) = { ( x ) => { var d = computeKthDigitOfPi( k ); g(
>> >> > f(
>> >> > x )
>> >> > ) } : (A => B) => (B => C) => A => C
>> >> >
>> >> > There are lots more infinite subsets where that one came from. The
>> >> > differences in complexity are not just manifest by silliness of the
>> >> > kind
>> >> > above. There are materially relevant differences that have to do with
>> >> > the
>> >> > internal representation of function and evaluation.
>> >> >
>> >> > Beyond that, consider the following function
>> >> >
>> >> > // provided A, B, C <: T with T supporting a certain algebraic
>> >> > structure
>> >> > Convolution_tau( f, g ) = { ( t ) => { integrate( f( t ) * g( tau - t
>> >> > ),
>> >> > posInf, negInf ) } } : (A => B) => (B => C) => A => C
>> >> >
>> >> > For the subset of types supporting a certain algebraic structure --
>> >> > i.e.
>> >> > we
>> >> > restrict the universe of quantification in the original theorem --
>> >> > this
>> >> > is a
>> >> > useful example of a way of getting functions from pairs of functions
>> >> > that is
>> >> > not a composition. Convolution is a useful notion that arises in
>> >> > physical
>> >> > sciences as well as in computation.
>> >> >
>> >> > The important point in all of this is that Scala's type system
>> >> > doesn't
>> >> > see
>> >> > certain aspects of computation that are still materially relevant to
>> >> > working
>> >> > programmers. The stuff that falls into this category can make
>> >> > practically
>> >> > useful documentation.
>> >> >
>> >> > Best wishes,
>> >> >
>> >> > --greg
>> >> >
>> >> > On Mon, Nov 16, 2009 at 6:53 AM, Ricky Clarkson
>> >> >
>> >> > wrote:
>> >> >>
>> >> >> I put it to you that my wife, who has never[1] programmed in her
>> >> >> life,
>> >> >> will be able to tell what the signature we have been discussing
>> >> >> means.
>> >> >>  She might need it rephrasing, as she's not familiar with Scala's
>> >> >> syntax.  Here's how I might rephrase it:
>> >> >>
>> >> >> There's a converter called f.  It takes in a value of type A, and
>> >> >> returns a value of type B.
>> >> >> There's a converter called g.  It takes in a value of type B, and
>> >> >> returns a value of type C.
>> >> >>
>> >> >> If I have f and g, and a value of type A, how would I get a value of
>> >> >> type
>> >> >> C?
>> >> >>
>> >> >> We might draw boxes on paper too, I don't know yet.
>> >> >>
>> >> >> I don't mind pandering to morons, to use your terms, not least as I
>> >> >> am
>> >> >> one in many contexts.  I'm not dismissing anyone.  I see no harm in
>> >> >> documenting signatures, even obvious ones, but I don't see it as
>> >> >> necessary.  It's ok to me if Scala cannot be used in organisations
>> >> >> that place so much emphasis on documenting obvious things, rather
>> >> >> than
>> >> >> having their staff understand fundamental concepts.  Note that I'm
>> >> >> not
>> >> >> even a committer though, and neither is Tony, to my knowledge.  If
>> >> >> you're unhappy with the documentation, I've never heard of a
>> >> >> documentation-adding patch being rejected.
>> >> >>
>> >> >> [1] I got her doing a little bit of Scheme a couple of years ago,
>> >> >> just
>> >> >> to keep her awake in a boring job.  She picked Ruby after I showed
>> >> >> her
>> >> >> code snippets from 13 languages, so she'll be learning that (as will
>> >> >> I) soon.
>> >> >>
>> >> >> 2009/11/16 Donald McLean :
>> >> >> > While there seems to be a strong "let us not pander to the morons"
>> >> >> > faction, please keep in mind that many of the people that you are
>> >> >> > so
>> >> >> > casually dismissing do have real power to prevent the adoption of
>> >> >> > Scala in their organizations. Failure to provide Scaladoc that is
>> >> >> > genuinely useful to people like me who are reasonably bright and
>> >> >> > competent developers but not strong theorists is a potentially
>> >> >> > fatal
>> >> >> > mistake. The Scala community will not, in many cases, get a second
>> >> >> > chance to prove that their product is NOT a toy dreamed up by
>> >> >> > insufferable academic elitists.
>> >> >> >
>> >> >> > On Mon, Nov 16, 2009 at 8:27 AM, Ricky Clarkson
>> >> >> > wrote:
>> >> >> >>> 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 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.
>> >> >> >>
>> >> >> >> Where possible, the function should be simple and obvious, and
>> >> >> >> types
>> >> >> >> should be sufficient to describe it.  As I said in another post,
>> >> >> >> I
>> >> >> >> agree with Tony, except that a good English description is
>> >> >> >> required
>> >> >> >> wherever one departs from the simple, obvious implementation.
>> >> >> > --
>> >> >> > 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
>> >> >> >
>> >> >>
>> >> >>
>> >> >>
>> >> >> --
>> >> >> Ricky Clarkson
>> >> >> Java and Scala Programmer, AD Holdings
>> >> >> +44 1565 770804
>> >> >> Skype: ricky_clarkson
>> >> >> Google Talk: ricky [dot] clarkson [at] gmail [dot] com
>> >> >> Google Wave: ricky [dot] clarkson [at] googlewave [dot] com
>> >> >
>> >> >
>> >> >
>> >> > --
>> >> > L.G. Meredith
>> >> > Managing Partner
>> >> > Biosimilarity LLC
>> >> > 1219 NW 83rd St
>> >> > Seattle, WA 98117
>> >> >
>> >> > +1 206.650.3740
>> >> >
>> >> > http://biosimilarity.blogspot.com
>> >> >
>> >>
>> >>
>> >>
>> >> --
>> >> Ricky Clarkson
>> >> Java and Scala Programmer, AD Holdings
>> >> +44 1565 770804
>> >> Skype: ricky_clarkson
>> >> Google Talk: ricky [dot] clarkson [at] gmail [dot] com
>> >> Google Wave: ricky [dot] clarkson [at] googlewave [dot] com
>> >
>> >
>> >
>> > --
>> > L.G. Meredith
>> > Managing Partner
>> > Biosimilarity LLC
>> > 1219 NW 83rd St
>> > Seattle, WA 98117
>> >
>> > +1 206.650.3740
>> >
>> > http://biosimilarity.blogspot.com
>> >
>>
>>
>>
>> --
>> Ricky Clarkson
>> Java and Scala Programmer, AD Holdings
>> +44 1565 770804
>> Skype: ricky_clarkson
>> Google Talk: ricky [dot] clarkson [at] gmail [dot] com
>> Google Wave: ricky [dot] clarkson [at] googlewave [dot] com
>
>
>
> --
> L.G. Meredith
> Managing Partner
> Biosimilarity LLC
> 1219 NW 83rd St
> Seattle, WA 98117
>
> +1 206.650.3740
>
> http://biosimilarity.blogspot.com
>

Johannes Rudolph
Joined: 2008-12-17,
User offline. Last seen 29 weeks 20 hours ago.
Re: Re: Scaladoc that is actually useful?

On Mon, Nov 16, 2009 at 6:24 PM, Ricky Clarkson
wrote:
> Johannes,
>
> Real machines?  Oh, yes, right.  So why are you programming in a
> language more abstract than assembly?  I'd wager that it's because
> most if not all the time when programming, it's simpler not to think
> in terms of real machines, real registers, real processor-level
> caches, etc.

Are you arguing? If yes, I don't understand, sorry...

See, you posted your argument under the topic "Scaladoc that is
actually useful?". Scaladoc that describes "a mathematical relation
such that each element of a given set (the domain of the function) is
associated with an element of another" is not a documentation of
Scala's implementation of that mapping.

In reality, a useful documentation should at least feature these points:
* When given a name, give me (the most concise?) description of what
the particular implementation does, that could include:
* the signature
* ScalaCheck conditions
* a description of the runtime time/space complexity if non-obvious
* prose or other means to describe other side-effects
* when given a function(ality) e.g. by signature, give me the name of
the Scala function(s) which implement/adhere to this signature

Traditionally many expect the following from a documentation:
* the ability to browse the namespace-hierarchy
* some meta-information how the namespace hierarchy was constructed
* some prose describing the big-architectural picture why the
namespace was created like it is

Actually, I was a little sad that I missed most of the argument while
being stuck on a train-ride on Thursday. I can appreciate Tony's
argument and I found most of the discussion entertaining, but it would
be nice if there would be gained something practical out of it.

Meredith Gregory
Joined: 2008-12-17,
User offline. Last seen 42 years 45 weeks ago.
Re: Re: Scaladoc that is actually useful?
Dear Brad,
LOL!
Best wishes,
--greg

On Mon, Nov 16, 2009 at 9:22 AM, Bradley Buchsbaum <brad [dot] buchsbaum [at] gmail [dot] com> wrote:
The good news is that we've narrowed it down a bit: there's either one or a countably infinite number of inhabitants of the function.  (If the latter, then I can only hope they're all happy.)





On Mon, Nov 16, 2009 at 12:17 PM, Johannes Rudolph <johannes [dot] rudolph [at] googlemail [dot] com> wrote:
On Mon, Nov 16, 2009 at 6:09 PM, Ricky Clarkson
<ricky [dot] clarkson [at] gmail [dot] com> wrote:
> Meredith,
>
> I don't think so, given that one defines a function as I do, something
> that takes in arguments and returns values.  If you're interested in
> what it *does*, you're interested in a procedure, not a function,
> according to the definitions I learned in high school.

How about keeping that discussion at least a bit in context? We are
talking about functions in Scala and most of us are using programming
languages to run programs on real machines. Real machines calculate
results normally by use of side-effects (space / time). So we never
deal with real pure functions in the mathematic sense if we speak
about real runnable programs. So a description of the time/space
complexity of an algorithm to run on a real machine needs some
specification about it's runtime behaviour.

--
Johannes

-----------------------------------------------
Johannes Rudolph
http://virtual-void.net



--
Bradley R. Buchsbaum
Rotman Research Institute
3560 Bathurst St.
Toronto, ON Canada M6A 2E1
email: bbuchsbaum [at] rotman-baycrest [dot] on [dot] ca



--
L.G. Meredith
Managing Partner
Biosimilarity LLC
1219 NW 83rd St
Seattle, WA 98117

+1 206.650.3740

http://biosimilarity.blogspot.com
Meredith Gregory
Joined: 2008-12-17,
User offline. Last seen 42 years 45 weeks ago.
Re: Re: Scaladoc that is actually useful?
Dear Ricky,

Are you saying that you take as your definition of a function a mathematical relation? So, for you the product space, A x B is the same as the function space A =>B? Here's a relation { (a, 1), (a, 2) }. Is this a function in your view?

Best wishes,

--greg

On Mon, Nov 16, 2009 at 9:25 AM, Ricky Clarkson <ricky [dot] clarkson [at] gmail [dot] com> wrote:
"(mathematics) a mathematical relation such that each element of a
given set (the domain of the function) is associated with an element
of another"

2009/11/16 Meredith Gregory <lgreg [dot] meredith [at] gmail [dot] com>:
> Dear Ricky,
> Thanks for your note. Here are some of the notions of function with which i
> have some familiarity
>
> lambda calculus
> recursive function theory
> set theoretic
> category theoretic
>
> All of these notions are consistent with my definitions and examples. Could
> you provide me your definition as it is fresh and may result in an insight
> for me?
> Best wishes,
> --greg
>
> On Mon, Nov 16, 2009 at 9:09 AM, Ricky Clarkson <ricky [dot] clarkson [at] gmail [dot] com>
> wrote:
>>
>> Meredith,
>>
>> I don't think so, given that one defines a function as I do, something
>> that takes in arguments and returns values.  If you're interested in
>> what it *does*, you're interested in a procedure, not a function,
>> according to the definitions I learned in high school.
>>
>> Ricky.
>>
>> 2009/11/16 Meredith Gregory <lgreg [dot] meredith [at] gmail [dot] com>:
>> > Dear Ricky,
>> >
>> > i think i just gave the Scala code for an infinite subset of the
>> > countably
>> > infinite set of functions that inhabit that type.
>> >
>> > Best wishes,
>> >
>> > --greg
>> >
>> > On Mon, Nov 16, 2009 at 8:44 AM, Ricky Clarkson
>> > <ricky [dot] clarkson [at] gmail [dot] com>
>> > wrote:
>> >>
>> >> Hi Meredith,
>> >>
>> >> Moved to scala-debate.
>> >>
>> >> Am I correct that there is only one *function* that inhabits that
>> >> signature?  There may be many procedures that you can perform, but
>> >> looking at the input types and return type, and assuming there's no
>> >> null, is there another function that the procedure could compute?
>> >>
>> >> Ricky.
>> >>
>> >> 2009/11/16 Meredith Gregory <lgreg [dot] meredith [at] gmail [dot] com>:
>> >> > Dear Ricky,
>> >> >
>> >> > i have responded to this argument repeatedly. i'm not sure why people
>> >> > are
>> >> > not getting this. Tony's argument is blatantly false. There are
>> >> > countably
>> >> > infinitely many inhabitants of the type (A => B) => (B => C) => A =>
>> >> > C.
>> >> > They
>> >> > are observably distinguished by running time and space consumption.
>> >> > Here
>> >> > is
>> >> > one infinite subset of that set: for each k in the natural numbers we
>> >> > have
>> >> >
>> >> > Compose_k( f, g ) = { ( x ) => { var d = computeKthDigitOfPi( k ); g(
>> >> > f(
>> >> > x )
>> >> > ) } : (A => B) => (B => C) => A => C
>> >> >
>> >> > There are lots more infinite subsets where that one came from. The
>> >> > differences in complexity are not just manifest by silliness of the
>> >> > kind
>> >> > above. There are materially relevant differences that have to do with
>> >> > the
>> >> > internal representation of function and evaluation.
>> >> >
>> >> > Beyond that, consider the following function
>> >> >
>> >> > // provided A, B, C <: T with T supporting a certain algebraic
>> >> > structure
>> >> > Convolution_tau( f, g ) = { ( t ) => { integrate( f( t ) * g( tau - t
>> >> > ),
>> >> > posInf, negInf ) } } : (A => B) => (B => C) => A => C
>> >> >
>> >> > For the subset of types supporting a certain algebraic structure --
>> >> > i.e.
>> >> > we
>> >> > restrict the universe of quantification in the original theorem --
>> >> > this
>> >> > is a
>> >> > useful example of a way of getting functions from pairs of functions
>> >> > that is
>> >> > not a composition. Convolution is a useful notion that arises in
>> >> > physical
>> >> > sciences as well as in computation.
>> >> >
>> >> > The important point in all of this is that Scala's type system
>> >> > doesn't
>> >> > see
>> >> > certain aspects of computation that are still materially relevant to
>> >> > working
>> >> > programmers. The stuff that falls into this category can make
>> >> > practically
>> >> > useful documentation.
>> >> >
>> >> > Best wishes,
>> >> >
>> >> > --greg
>> >> >
>> >> > On Mon, Nov 16, 2009 at 6:53 AM, Ricky Clarkson
>> >> > <ricky [dot] clarkson [at] gmail [dot] com>
>> >> > wrote:
>> >> >>
>> >> >> I put it to you that my wife, who has never[1] programmed in her
>> >> >> life,
>> >> >> will be able to tell what the signature we have been discussing
>> >> >> means.
>> >> >>  She might need it rephrasing, as she's not familiar with Scala's
>> >> >> syntax.  Here's how I might rephrase it:
>> >> >>
>> >> >> There's a converter called f.  It takes in a value of type A, and
>> >> >> returns a value of type B.
>> >> >> There's a converter called g.  It takes in a value of type B, and
>> >> >> returns a value of type C.
>> >> >>
>> >> >> If I have f and g, and a value of type A, how would I get a value of
>> >> >> type
>> >> >> C?
>> >> >>
>> >> >> We might draw boxes on paper too, I don't know yet.
>> >> >>
>> >> >> I don't mind pandering to morons, to use your terms, not least as I
>> >> >> am
>> >> >> one in many contexts.  I'm not dismissing anyone.  I see no harm in
>> >> >> documenting signatures, even obvious ones, but I don't see it as
>> >> >> necessary.  It's ok to me if Scala cannot be used in organisations
>> >> >> that place so much emphasis on documenting obvious things, rather
>> >> >> than
>> >> >> having their staff understand fundamental concepts.  Note that I'm
>> >> >> not
>> >> >> even a committer though, and neither is Tony, to my knowledge.  If
>> >> >> you're unhappy with the documentation, I've never heard of a
>> >> >> documentation-adding patch being rejected.
>> >> >>
>> >> >> [1] I got her doing a little bit of Scheme a couple of years ago,
>> >> >> just
>> >> >> to keep her awake in a boring job.  She picked Ruby after I showed
>> >> >> her
>> >> >> code snippets from 13 languages, so she'll be learning that (as will
>> >> >> I) soon.
>> >> >>
>> >> >> 2009/11/16 Donald McLean <dmclean62 [at] gmail [dot] com>:
>> >> >> > While there seems to be a strong "let us not pander to the morons"
>> >> >> > faction, please keep in mind that many of the people that you are
>> >> >> > so
>> >> >> > casually dismissing do have real power to prevent the adoption of
>> >> >> > Scala in their organizations. Failure to provide Scaladoc that is
>> >> >> > genuinely useful to people like me who are reasonably bright and
>> >> >> > competent developers but not strong theorists is a potentially
>> >> >> > fatal
>> >> >> > mistake. The Scala community will not, in many cases, get a second
>> >> >> > chance to prove that their product is NOT a toy dreamed up by
>> >> >> > insufferable academic elitists.
>> >> >> >
>> >> >> > On Mon, Nov 16, 2009 at 8:27 AM, Ricky Clarkson
>> >> >> > <ricky [dot] clarkson [at] gmail [dot] com> wrote:
>> >> >> >>> 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 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.
>> >> >> >>
>> >> >> >> Where possible, the function should be simple and obvious, and
>> >> >> >> types
>> >> >> >> should be sufficient to describe it.  As I said in another post,
>> >> >> >> I
>> >> >> >> agree with Tony, except that a good English description is
>> >> >> >> required
>> >> >> >> wherever one departs from the simple, obvious implementation.
>> >> >> > --
>> >> >> > 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
>> >> >> >
>> >> >>
>> >> >>
>> >> >>
>> >> >> --
>> >> >> Ricky Clarkson
>> >> >> Java and Scala Programmer, AD Holdings
>> >> >> +44 1565 770804
>> >> >> Skype: ricky_clarkson
>> >> >> Google Talk: ricky [dot] clarkson [at] gmail [dot] com
>> >> >> Google Wave: ricky [dot] clarkson [at] googlewave [dot] com
>> >> >
>> >> >
>> >> >
>> >> > --
>> >> > L.G. Meredith
>> >> > Managing Partner
>> >> > Biosimilarity LLC
>> >> > 1219 NW 83rd St
>> >> > Seattle, WA 98117
>> >> >
>> >> > +1 206.650.3740
>> >> >
>> >> > http://biosimilarity.blogspot.com
>> >> >
>> >>
>> >>
>> >>
>> >> --
>> >> Ricky Clarkson
>> >> Java and Scala Programmer, AD Holdings
>> >> +44 1565 770804
>> >> Skype: ricky_clarkson
>> >> Google Talk: ricky [dot] clarkson [at] gmail [dot] com
>> >> Google Wave: ricky [dot] clarkson [at] googlewave [dot] com
>> >
>> >
>> >
>> > --
>> > L.G. Meredith
>> > Managing Partner
>> > Biosimilarity LLC
>> > 1219 NW 83rd St
>> > Seattle, WA 98117
>> >
>> > +1 206.650.3740
>> >
>> > http://biosimilarity.blogspot.com
>> >
>>
>>
>>
>> --
>> Ricky Clarkson
>> Java and Scala Programmer, AD Holdings
>> +44 1565 770804
>> Skype: ricky_clarkson
>> Google Talk: ricky [dot] clarkson [at] gmail [dot] com
>> Google Wave: ricky [dot] clarkson [at] googlewave [dot] com
>
>
>
> --
> L.G. Meredith
> Managing Partner
> Biosimilarity LLC
> 1219 NW 83rd St
> Seattle, WA 98117
>
> +1 206.650.3740
>
> http://biosimilarity.blogspot.com
>



--
Ricky Clarkson
Java and Scala Programmer, AD Holdings
+44 1565 770804
Skype: ricky_clarkson
Google Talk: ricky [dot] clarkson [at] gmail [dot] com
Google Wave: ricky [dot] clarkson [at] googlewave [dot] com



--
L.G. Meredith
Managing Partner
Biosimilarity LLC
1219 NW 83rd St
Seattle, WA 98117

+1 206.650.3740

http://biosimilarity.blogspot.com

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