[Haskell-cafe] Documentation (was: ANN: text 0.5, a major revision of the Unicode text library)

[José Pedro Magalhães]

Hi,

While I agree that the documentation of Data.Generics is not perfect, I do
not think it is possible to have the haddock documentation be
self-contained. For a thorough understanding of syb, a user has to read the
two initial papers, which are linked from the haddock documentation. I also
do not think it's reasonable to explain all the details beyond monads in the
Control.Monad haddock, for instance.

For the problem at hand (a Data instance for Text), I can only say that
generic programming and abstract datatypes do not mix too well (although
there is work on the area, see [1]). Generics work by exploiting the
structure of types, and if that structure is explicitly kept hidden then
(rather ad hoc) workarounds have to be used. See, for example, the Data
instance for Array:

-- The Data instance for Array preserves data abstraction at the cost of
> -- inefficiency. We omit reflection services for the sake of data
> abstraction.
> instance (Typeable a, Data b, Ix a) => Data (Array a b)
>  where
>   gfoldl f z a = z (listArray (bounds a)) `f` (elems a)
>   toConstr _   = error "toConstr"
>   gunfold _ _  = error "gunfold"
>   dataTypeOf _ = mkNorepType "Data.Array.Array"
>


Cheers,
Pedro

[1] http://www.comlab.ox.ac.uk/publications/publication1385-abstract.html

On Sun, Oct 11, 2009 at 14:58, John Lato <jwlato at gmail.com> wrote:

> For anyone writing introductions to generic programming, take this as
> a plea from Haskellers everywhere.  If one of the RWH authors can't
> understand how to make use of these techniques, what hope do the rest
> of us have?
>
> John Lato
>
> P.S. Some might wryly note that I'm the maintainer of a package which
> is also known for incomprehensible documentation.  To which I would
> reply that our effort is much newer, I consider it a problem, and it's
> being worked on, contrasted to the state of GP where similarly
> impenetrable documentation has been and continues to be the norm.
>
> >
> > From: "Bryan O'Sullivan" <bos at serpentine.com>
> >
> > I think maybe someone else will have to take a crack at a Data instance
> for
> > Text, because the documentation for Data.Data is not written in English.
> In
> > its syntax and structure, it closely hews to what we think of as English,
> > but it is the kind of documentation that can only be understood by
> someone
> > who already knows what it is going to say.
> >
> > This is an exemplar of my experience with the cottage industry of generic
> > programming in Haskell: I'd really quite like to use the stuff, but for
> > goodness's sake, o beloved researchers, please aim your expository papers
> at
> > non-specialists once in a while. An endless chain of papers of the form
> "my
> > technique, which you won't understand, is better than this other
> technique,
> > which you haven't read about and won't anyway understand, in subtle ways
> > that you won't understand" does not feel to me like progress.
> >
> > Yours in some misery and frustration,
> > Bryan.
> _______________________________________________
> Haskell-Cafe mailing list
> Haskell-Cafe at haskell.org
> http://www.haskell.org/mailman/listinfo/haskell-cafe
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://www.haskell.org/pipermail/haskell-cafe/attachments/20091019/f633ba62/attachment.html