On Wed, 30 Jan 2008, Jules Bean wrote:

Neil Mitchell wrote:

...

For a start, its probably a good idea to mention that cos is an abbreviation of cosine (most people will know, but its handy to state it). Secondly, and much more importantly, it should state whether these measurements are in degrees or radians.

In the early versions of the functionalMetaPost package the trigonometric functions were simply mapped to MetaPost's trigonometric functions. But MetaPost uses degrees, whereas Haskell uses radians (which is mathematically more useful).

...

It should also state things like acos is the inverse of cos - its been a while since I last used trig and I had to look it up!!!

I imagine the laziness here was because these all match their names in the traditional libc, accessable via manpages.

Can haddock be advised to fetch documentation from existing man pages instead from Haskell comments? :-)

Johan Tibell wrote:

...

I imagine the laziness here was because these all match their names in the traditional libc, accessable via manpages.

You may not consider that an excuse :)

I don't! To do something about it I'll adopt Network.Socket and document that (I did the same with some other base module half a year ago.) I invite others to do the same, the Prelude would be a good start. It doesn't take much time. There are interesting things to document like how error conditions are handled, etc.

maybe start from http://www.haskell.org/onlinereport/standard-prelude.html ... hmm, wait, that doesn't give much comments, but at least it gives a specification-style implementation and type signature, which must be why I look there ~Isaac

On Wed, 30 Jan 2008, Robin Green wrote:

On Wed, 30 Jan 2008 13:15:41 +0000 Jules Bean wrote:

...

Neil Mitchell wrote:

...

For a start, its probably a good idea to mention that cos is an abbreviation of cosine (most people will know, but its handy to state it). Secondly, and much more importantly, it should state whether these measurements are in degrees or radians. It should also state things like acos is the inverse of cos - its been a while since I last used trig and I had to look it up!!!

I imagine the laziness here was because these all match their names in the traditional libc, accessable via manpages.

Neil is on Windows. Windows doesn't have man pages (or libc).

Standard C math library does always contain trigonometric functions - doesn't it?

On Thu, 2008-01-31 at 02:18 +0000, Neil Mitchell wrote:

Hi

...

...

Neil is on Windows. Windows doesn't have man pages (or libc).

Standard C math library does always contain trigonometric functions - doesn't it?

My libc (as installed by Visual Studio, and called msvscrt) comes with all these functions, but no manpages, and the MSDN (manpages for Windows) are too big to install on this machine. I answered my queries in the end by googling and finding the GNU libc documentation, but thats not where I want it.

It isn't something that would throw a C programmer off, but it is something that could confuse a pure Haskell programmer. And the only way I could be sure of radians versus degrees was by trying it out, not a great strategy for determining the implementation of functions!

Uh, why not? Often that's exactly what I do as checking even conveniently located documentation is more time consuming than just trying it.

Derek Elkins wrote:

On Thu, 2008-01-31 at 02:18 +0000, Neil Mitchell wrote: ...

...

It isn't something that would throw a C programmer off, but it is something that could confuse a pure Haskell programmer. And the only way I could be sure of radians versus degrees was by trying it out, not a great strategy for determining the implementation of functions!

Uh, why not? Often that's exactly what I do as checking even conveniently located documentation is more time consuming than just trying it.

I agree, but at the risk of veering uncharacteristically off-topic for haskell-cafe, I think it's an interesting example of the degree of assurance about correctness we're willing to accept in practice, in real development. We discover a function called, say, "cos", probably by guessing it's name, run a very small number of simple tests on it, see the answers we expect, and decide that it's the function we want. Does anyone want to defend that on safety/correctness grounds? But some of us do it anyway. (I'll have to work this into the upcoming paper I mentioned, "In defense of arbitrary untracked effects in high assurance software." I'm glad Graham Fawcett volunteered to co-author!)

Derek Elkins wrote:

On Wed, 2008-01-30 at 22:19 -0500, Anton van Straaten wrote: ...

...

We discover a function called, say, "cos", probably by guessing it's name, run a very small number of simple tests on it, see the answers we expect, and decide that it's the function we want. Does anyone want to defend that on safety/correctness grounds? But some of us do it anyway.

It depends on the extent. Deciding between degrees and radians, this works perfectly if you have any idea what you are doing.

But deciding between degrees and radians is only one of the assumptions you'd be making, if you don't check the docs. In general, this argument sounds similar to the sort of arguments that are given in defense of all sorts of unsafe activities -- dynamic typechecking comes to mind, or unhygienic macros: "works perfectly if you have any idea what you are doing". While it may usually be true, it's often not considered a valid argument if safety and correctness are important.

Arguably, this -is- more defensible on a safety/correctness grounds than reading the documentation. Documentation can be out of date or wrong or right but the implementation is wrong. So it comes down to a matter of trust/convincing.

Reading the documentation alone isn't enough from a correctness perspective - you also need to test. As Reagan liked to put it, trust but verify. But similarly, testing alone isn't enough. There could be caveats in the documentation that could affect your program, that you don't detect in your tests. And yes, you also might come across a discrepancy between documentation and the actual behavior, which is something you'd want to investigate if correctness is important. Actual instances of discrepancies between documentation and code are a bug, but the fact that the two can get out of sync is a feature: it acts as a cross-check, and the purpose of cross-checks is that sometimes they fail. If you're concerned about safety and correctness, then ignoring available information about functions you use, and assuming that behavior is as you expect, still seems hard to defend, to me.

Henning Thielemann wrote:

On Thu, 31 Jan 2008, Anton van Straaten wrote:

...

Derek Elkins wrote:

...

Arguably, this -is- more defensible on a safety/correctness grounds than reading the documentation. Documentation can be out of date or wrong or right but the implementation is wrong. So it comes down to a matter of trust/convincing. Reading the documentation alone isn't enough from a correctness perspective - you also need to test. As Reagan liked to put it, trust but verify.

... wasn't this Lenin?

:-)

Reagan didn't invent the phrase, but he used it quite often[*], and that's where I remember it from. Lenin would presumably have said "doveryai, no proveryai", an old Russian saying. [*] http://en.wikipedia.org/wiki/Trust,_but_Verify

On 30 Jan 2008, at 7:19 PM, Anton van Straaten wrote:

Derek Elkins wrote:

...

...

It isn't something that would throw a C programmer off, but it is something that could confuse a pure Haskell programmer. And the only way I could be sure of radians versus degrees was by trying it out, not a great strategy for determining the implementation of functions! Uh, why not? Often that's exactly what I do as checking even conveniently located documentation is more time consuming than just

On Thu, 2008-01-31 at 02:18 +0000, Neil Mitchell wrote: ... trying it.

I agree, but at the risk of veering uncharacteristically off-topic for haskell-cafe, I think it's an interesting example of the degree of assurance about correctness we're willing to accept in practice, in real development.

We discover a function called, say, "cos", probably by guessing it's name, run a very small number of simple tests on it, see the answers we expect, and decide that it's the function we want.

True enough; more complicated tests seem to reveal the opposite conclusion:

quickCheck $ \ x -> cos (x + 2*pi) == cos x Falsifiable, after 2 tests: -1.0

jcc

On Wed, 2008-01-30 at 13:15 +0000, Jules Bean wrote:

Neil Mitchell wrote:

...

For a start, its probably a good idea to mention that cos is an abbreviation of cosine (most people will know, but its handy to state it). Secondly, and much more importantly, it should state whether these measurements are in degrees or radians. It should also state things like acos is the inverse of cos - its been a while since I last used trig and I had to look it up!!!

I imagine the laziness here was because these all match their names in the traditional libc, accessable via manpages.

And, uh, well, the Report... except, entertainingly, the Report doesn't actually define most of these except by reference.

You may not consider that an excuse :)

Ultimately, as others have said, it would be nice to have reference documentation all in one place and one format.