[Haskell-cafe] "doctest" for haskell -- a good project?

[Thomas Schilling]

On 22 mar 2008, at 13.17, Neil Mitchell wrote:

> Hi
>
>>  One idea that does strike me is that it would be super useful to  
>> have
>>  the ability in ghci to extract the haddocks associated with a  
>> function.
>>
>>> :doc map
>>
>>  would result in:
>>
>>      -- | 'map' @f xs@ is the list obtained by applying @f@ to  
>> each element
>>      -- of @xs@, i.e.,
>>      --
>>      -- > map f [x1, x2, ..., xn] == [f x1, f x2, ..
>>      -- > map f [x1, x2, ...] == [f x1, f x2, ...]
>
> That will be in Hoogle 4, as it does already directly relate to what
> Hoogle has to do.
>
> As for doctest, i think that could be implemented as a --warn flag to
> Haddock, and might be a useful thing to have. For example "90% of the
> base library has documentation, please go add documentation to
> 'sinh'", as a warning message.
>


Though that would be a nice feature, too, I think you misunderstood  
what a doctest is.

A doctest is a unit test in the documentation.  This way it serves as  
a usage example as well as a formal specification of the semantics.   
I think we already have some way to run quickchecks inside  
documentation, but I can't remember what it was that could do that.

/ Thomas