Improving library documentation

If you find standard library documentation lacking in any way, please log it here. At the minimum record what library/module/function isn't properly documented. Please also suggest how to improve the documentation, in terms of examples, explanations and so on.

Example:

   package base
   Data.List
   unfoldr

   An example would be useful. Perhaps:

       -- A simple use of unfoldr:
       --
       -- > unfoldr (\b -> if b == 0 then Nothing else Just (b, b-1)) 10
       -- >  [10,9,8,7,6,5,4,3,2,1]
       --

dons 00:31, 26 November 2006 (UTC)

Tag your submission with your name by using 4 ~ characters, which will be expanded to your name and the date.

If you'd like, you can directly submit your suggestion as a darcs patch via the bug tracking system.

Please add your comments under the appropriate package:

General Haddock

I wish haddock generated a link to the parent module when it creates the page for a given module. I may implement this myself, but I wanted to make sure this wishlist item was recorded somewhere :) Dagit 08:49, 27 November 2006 (UTC)

base

   package base
   Data.Array.IO and Data.Array.MArray
   descriptions

   An example would be usefull.  Arrays can be very difficult when you see
   them the very first time ever with the assumption that you want to try 
   them right now and that Haskell is a relatively new to you. Maybe something 
   like this could be added into the descriptions of the array-modules.

   module Main where
   
   import Data.Array.IO
   
   -- Replace each element with 1/i, where i is the index starting from 1.
   -- Loop uses array reading and writing.
   loop :: IOUArray Int Double -> Int -> Int -> IO ()
   loop arr i aLast  
       | i > aLast = return ()
       | otherwise = do
            val <- readArray arr i
            writeArray arr i (val / (1+fromIntegral i))
            loop arr (i+1) aLast

    main = do
       arr <- newArray (0,9) 1.0   -- initialise an array with 10 doubles.
       loop arr 0 9                -- selfmade loop over elements
       arr <- mapArray (+1) arr    -- a map over elements
       elems <- getElems arr
       putStrLn $ "Array elements: " ++ (show elems)

    Isto 14:43, 26 November 2006 (UTC)

network

   package network
   Network.Socket
   descriptions

   Lacking documentation on practically all non-typed parameters.
   take recv :: Socket -> Int -> IO String
   What is the int there? Some sort of flag?

   Also, hoogle links are broken, needed to use google to get there.

   Zut 19:24, 24 November 2007 (UTC)

STM

   package stm
   Control.Concurrent.STM.TChan
   Control.Concurrent.STM.TMVar
   function comments

   TMVar, TChan: While mostly intuitive, the functions could use some comments to simplify reference.
    Imix 10:00, 14 December 2006 (UTC)

Control.Applicative, Data.Traversable, Data.Foldable

Some examples of how these modules can be used would be extremely helpful. It's hard for me to extract examples from the McBride and Paterson paper, because of the notation and because the examples are mixed in with the axioms and proofs.

(This comment really applies to any module where the description contains a link to a PDF of an academic paper and no examples.)

SethGordon 14:19, 14 December 2006 (UTC)

The problem is that those classes do not make sense without axioms, a set of axioms defines the meaning. What do you mean by an inappropriate notation? Personally I feel that “→” is more readable than “->” and “∘” than “.”. --Beroal 05:29, 20 January 2010 (UTC)