- About Scala
- Documentation
- Code Examples
- Software
- Scala Developers

# Scaladoc that is actually useful?

Thu, 2009-11-12, 18:08

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

Thu, 2009-11-12, 21:57

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

Thu, 2009-11-12, 22:07

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

>

Thu, 2009-11-12, 22:17

#4
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

Thu, 2009-11-12, 22:27

#5
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

>

>

Thu, 2009-11-12, 22:37

#6
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

Thu, 2009-11-12, 22:37

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

Thu, 2009-11-12, 22:47

#8
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

>

>

Thu, 2009-11-12, 22:57

#9
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

Thu, 2009-11-12, 22:57

#10
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:

"Deconstruction of the

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:

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

Thu, 2009-11-12, 23:07

#11
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

>

>

Thu, 2009-11-12, 23:17

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

>

Thu, 2009-11-12, 23:27

#13
Re: Scaladoc that is actually useful?

On Thu, Nov 12, 2009 at 3:55 PM, Tony Morris <tonymorris [at] gmail [dot] com> wrote:

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

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

Thu, 2009-11-12, 23:37

#14
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

Fri, 2009-11-13, 00:07

#15
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:

On Thu, Nov 12, 2009 at 3:08 PM, Donald McLean <dmclean62 [at] gmail [dot] com> wrote:

--

Daniel C. Sobral

Veni, vidi, veterni.

Here's what I see for LinkedList on Scala 2.7.4:

`class`

*LinkedList*[*A*](`val`

*elem*: A,`val`

*next*: LinkedList[A])`extends`

SingleLinkedList[A, LinkedList[A]]

- This class implements single linked lists where both the head (
`elem`

) and the tail (`next`

) are mutable.

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.

Fri, 2009-11-13, 00:17

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

Fri, 2009-11-13, 00:27

#17
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

>

>

Fri, 2009-11-13, 02:17

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

Fri, 2009-11-13, 02:17

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

>

>

Fri, 2009-11-13, 07:17

#20
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

Fri, 2009-11-13, 17:57

#21
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

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.

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:

--

L.G. Meredith

Managing Partner

Biosimilarity LLC

1219 NW 83rd St

Seattle, WA 98117

+1 206.650.3740

http://biosimilarity.blogspot.com

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

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

Fri, 2009-11-13, 18:37

#22
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

Fri, 2009-11-13, 19:07

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

Fri, 2009-11-13, 19:27

#24
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:

--

L.G. Meredith

Managing Partner

Biosimilarity LLC

1219 NW 83rd St

Seattle, WA 98117

+1 206.650.3740

http://biosimilarity.blogspot.com

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

Fri, 2009-11-13, 21:07

#25
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:

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.

Fri, 2009-11-13, 21:27

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

Fri, 2009-11-13, 21:37

#27
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

Fri, 2009-11-13, 21:47

#28
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:

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

Sat, 2009-11-14, 00:17

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

>>

Sun, 2009-11-15, 16:37

#30
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

Sun, 2009-11-15, 16:47

#31
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

Sun, 2009-11-15, 16:57

#32
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

Sun, 2009-11-15, 17:07

#33
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

Sun, 2009-11-15, 21:07

#34
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

Best wishes,

--greg

On Sun, Nov 15, 2009 at 7:53 AM, Randall R Schulz <rschulz [at] sonic [dot] net> wrote:

--

L.G. Meredith

Managing Partner

Biosimilarity LLC

1219 NW 83rd St

Seattle, WA 98117

+1 206.650.3740

http://biosimilarity.blogspot.com

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

Mon, 2009-11-16, 14:37

#35
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

>

>

Mon, 2009-11-16, 15:27

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

Mon, 2009-11-16, 15:57

#37
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

>

Mon, 2009-11-16, 16:17

#38
Re: Re: Scaladoc that is actually useful?

On Mon, Nov 16, 2009 at 8:24 AM, Donald McLean <dmclean62 [at] gmail [dot] com> wrote:

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)

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)

Mon, 2009-11-16, 17:47

#39
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:

--

L.G. Meredith

Managing Partner

Biosimilarity LLC

1219 NW 83rd St

Seattle, WA 98117

+1 206.650.3740

http://biosimilarity.blogspot.com

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

Mon, 2009-11-16, 17:57

#40
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

>

Mon, 2009-11-16, 18:17

#41
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

Best wishes,

--greg

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

--

L.G. Meredith

Managing Partner

Biosimilarity LLC

1219 NW 83rd St

Seattle, WA 98117

+1 206.650.3740

http://biosimilarity.blogspot.com

i think i just gave the Scala code for an infinite subset of the countably infinite set of

**that inhabit that type.***functions*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

Mon, 2009-11-16, 18:27

#42
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

>

Mon, 2009-11-16, 18:27

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

Mon, 2009-11-16, 18:27

#44
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:

--

Bradley R. Buchsbaum

Rotman Research Institute

3560 Bathurst St.

Toronto, ON Canada M6A 2E1

email: bbuchsbaum [at] rotman-baycrest [dot] on [dot] ca

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

Mon, 2009-11-16, 18:37

#45
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

Best wishes,

--greg

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

--

L.G. Meredith

Managing Partner

Biosimilarity LLC

1219 NW 83rd St

Seattle, WA 98117

+1 206.650.3740

http://biosimilarity.blogspot.com

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

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

Mon, 2009-11-16, 18:37

#46
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

>

Mon, 2009-11-16, 18:47

#47
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

>

Mon, 2009-11-16, 18:57

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

Mon, 2009-11-16, 18:57

#49
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:

--

L.G. Meredith

Managing Partner

Biosimilarity LLC

1219 NW 83rd St

Seattle, WA 98117

+1 206.650.3740

http://biosimilarity.blogspot.com

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

Mon, 2009-11-16, 18:57

#50
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:

--

L.G. Meredith

Managing Partner

Biosimilarity LLC

1219 NW 83rd St

Seattle, WA 98117

+1 206.650.3740

http://biosimilarity.blogspot.com

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

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

>