Haddock documentation of Data.Array.* is confusing

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

Haddock documentation of Data.Array.* is confusing

Bugzilla from alfonso.acosta@gmail.com
Hi,

Excuse me for the subject, but IMHO is absolutely true. Anyhow, the
purpose of this message is not merely to rant about it (which I know
doesn't help) but to illustrate the possible impression of a Haskell
newcomers.

It's been a long long time since I last used arrays in Haskell (lists
are normally just fine for me) so I checked the docs to refresh my
memory. This is the result of my experience:

The first thing I checked was Data.Array which ... just shows function
names without signatures!

OK, I followed the advice shown in "Data.Array" and tried to
understand the more generic interface of Data.IArray.

Fine, the documentation is much better, however it mentions
Data.Array.Base, whose documentation link is missing :S

I was suprised to see that even if all the functions of Data.IArray
(i.e. array, listArray ... ) are perfectly sensible and generic (which
is nice), they are not part of ot the IArray multiparameter class.

So I wondered .. how can someone add its own implementation of
inmutable arrays to the IArray interface? It was obvious that "bounds"
(the only method of the IArray typeclass) was not going to enough, but
I tried anyway with a naive example.

{-# LANGUAGE FlexibleInstances, MultiParamTypeClasses #-}
data Ix i => LArray i e = LArray [e] (i,i)

instance IArray LArray e where
-- bounds :: (Ix i, IArray LArray e) => LArray i e -> (i,i)
 bounds (LArray _ b) = b

GHC warned me about missing definitions for some"unsafe" methods of
ArrayI which .... as expected, belong to the "phantom" Data.Array.Base
module.

The sources of Data.Array.Base revealed that the purpose of hiding
them was to protect the user.

Someone who wants add an array implementation to the IArray interface
should use Data.Array.Base but why would it hurt to add a note in
IArray mentioning it? and Why is Data.Array.Base hidden for Haddock
(especially when there are some broken links pointing to it)?

Cheers,

Fons
_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: Haddock documentation of Data.Array.* is confusing

Bulat Ziganshin-2
Hello Alfonso,

Tuesday, February 12, 2008, 11:32:20 PM, you wrote:

> Excuse me for the subject, but IMHO is absolutely true. Anyhow, the

of course, you are right, but for practical goals i may suggest just
to read module sources instead of reading [had]docs. seeing the
implementation is much more interesting, after all. especially when you
are so cool that you are going to add your own instance


--
Best regards,
 Bulat                            mailto:[hidden email]

_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: Haddock documentation of Data.Array.* is confusing

Bugzilla from alfonso.acosta@gmail.com
On Wed, Feb 20, 2008 at 10:17 PM, Bulat Ziganshin
<[hidden email]> wrote:
> Hello Alfonso,
>
>
>  Tuesday, February 12, 2008, 11:32:20 PM, you wrote:
>
>  > Excuse me for the subject, but IMHO is absolutely true. Anyhow, the
>
>  of course, you are right, but for practical goals i may suggest just
>  to read module sources instead of reading [had]docs.

Well, that's what I was forced to do in the end, but I still think
that the haddock documentation should be clear enough for most of the
cases, and, when it comes to  Data.Array* it could certainly be
improved.

> seeing the
>  implementation is much more interesting, after all. especially when you
>  are so cool that you are going to add your own instance

I don't think that "being cool" had anything to do with it. My only
purpose was to understand the desing of the interface for inmutable
arrays.
_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe