Documentation for GHC primops
Dear GHC users This message is a request for help with a well-contained task that will improve GHC's Haddock documentation. GHC provides lots of primitive operations. They are described in a single ASCII files primpos.txt.pp; the description in that file gives types and English-language descriptions, as well as some other GHC-ish information. This description file is chomped up by a pre-processor (genprimopcode), which produces either (a) Haskell source code for data types describing the primops [these modules become part of GHC itself), or (b) Latex stuff which can be part of a document. You can see the output in Section 4.4 of the External Core document (http://www.haskell.org/ghc/docs/papers/core.ps.gz) However, there's no Haddock document describing all these primops!! Although they are all available through the module GHC.Exts, the Haddock documentation for GHC.Exts says nothing at all about them. http://www.haskell.org/ghc/docs/latest/html/libraries/base/GHC.Exts.html Reason: there is no Haskell source code for GHC.Prim, the pseudo-module that exports all the primops. What we want is to generate GHC.Prim.hs from primops.txt.pp. This .hs file would not be fed to GHC; rather it'd just be there so that Haddock could see it. For example: module GHC.Prim( ...list all primops... ) where (+#) :: Int# -> Int# -> Int# --| Adds two unboxed Ints ...etc... you get the idea. No Haskell code, only type signatures. Would someone cares to write this new backend to "genprimopcode". The latter is a Haskell program that can parse primops.txt.pp, and already has two back ends (a) and (b) above. What we want is to add (c) generate Haskell that Haddock can understand. Note that the documentation itself is already written -- it's in primpos.txt.pp. That's what's so tantalising. All that we need is to mangle it into Haddock. Any volunteers? It doesn't involve touching GHC itself. "gemprimopcode" is a completely standalone Haskell program, currently some 730 lines long. Simon
Would someone cares to write this new backend to "genprimopcode". The latter is a Haskell program that can parse primops.txt.pp, and already has two back ends (a) and (b) above. What we want is to add (c) generate Haskell that Haddock can understand.
Note that the documentation itself is already written -- it's in primpos.txt.pp. That's what's so tantalising. All that we need is to mangle it into Haddock.
Any volunteers? It doesn't involve touching GHC itself. "gemprimopcode" is a completely standalone Haskell program, currently some 730 lines long.
If no one else is willing to do it, count me in. But before I agree to this task, I have some further questions: * How much time will it probably take? I know this depends on one's Haskell proficiency, so what is your estimate for an advanced Haskell programmer? * My first guess is this will only (?) involve writing a function similar to 'gen_latex_doc', is that correct? Regards, Jens
On Wed, 2005-06-29 at 16:49 +0200, Jens Fisseler wrote:
Would someone cares to write this new backend to "genprimopcode". The latter is a Haskell program that can parse primops.txt.pp, and already has two back ends (a) and (b) above. What we want is to add (c) generate Haskell that Haddock can understand.
Note that the documentation itself is already written -- it's in primpos.txt.pp. That's what's so tantalising. All that we need is to mangle it into Haddock.
Any volunteers? It doesn't involve touching GHC itself. "gemprimopcode" is a completely standalone Haskell program, currently some 730 lines long.
If no one else is willing to do it, count me in.
You may like to start by borrowing some code from a code generator written for Gtk2Hs which produces Haskell modules with Haddock comments (extracted from another source). So in particular, there is code for formatting Haddock markup. You can see it here: http://cvs.sourceforge.net/viewcvs.py/gtk2hs/gtk2hs/tools/apiGen/ and specifically: http://cvs.sourceforge.net/viewcvs.py/gtk2hs/gtk2hs/tools/apiGen/FormatDocs.hs?rev=1.12&view=auto I'm not claiming it's highly general and usable for your purpose as it is now but it might be a useful source for code snippets. Duncan
Hello Simon, You are requested us to give you examples of bad messages about program errors. This message is due to use of "all" instead of "and". in this case it would be great to hear that "all" has type of "(a -> Bool) -> [a] -> Bool" instead of needed "[Bool] -> Bool". May be in this case GHC tries to be smarter than needed :-) data PackedFilePath = PackedFilePath { fpPackedDirectory :: !String , fpPackedBasename :: !String , fpHash :: Int } map2eq f x y = (f x) == (f y) instance Eq PackedFilePath where a==b = all [ map2eq fpHash a b , map2eq fpPackedBasename a b , map2eq fpPackedDirectory a b ] c.hs:10:11: Couldn't match `Bool' against `t -> t1' Expected type: Bool Inferred type: t -> t1 Expected type: Bool Inferred type: [a] -> Bool Probable cause: `all' is applied to too few arguments in the call (all [map2eq fpHash a b, map2eq fpPackedBasename a b, map2eq fpPackedDirectory a b]) The HUGS message again a little more informative: ERROR "C:\temp\c.hs":10 - Type error in application *** Expression : all [map2eq fpHash a b,map2eq fpPackedBasename a b,map2eq fpPackedDirectory a b] *** Term : [map2eq fpHash a b,map2eq fpPackedBasename a b,map2eq fpPackedDirectory a b] *** Type : [Bool] *** Does not match : a -> Bool btw, i share the viewpoint that GHC messages are close to unusable. The main information i extract from them is an exact error location. may be (may be!) it is better to render error messages in terms of terms ;) with KNOWN TYPES, such as "all" in this case. while the Haskell officially is functional language and any term can be a fixed function or some data, in real programs there is some base things which have a fixed meaning and organize the whole computation process. concentrating on such things (i.e. functions with known types) instead of concentrating on types of isolated terms may approach you to not-so-smart programmers using GHC like me :) may be it is a viewpoint of old imperative programmer which accustomed to having two different beasts - procedures with well-known types and data which can or cannot be processed by these procedures, but both GHC and HUGS in this example says nothing about that cause of error message was that "all" wants arguments of this concrete types -- Best regards, Bulat mailto:bulatz@HotPOP.com
participants (4)
-
Bulat Ziganshin -
Duncan Coutts -
Jens Fisseler -
Simon Peyton-Jones