From ashley at semantic.org  Wed Feb  7 02:17:59 2007
From: ashley at semantic.org (Ashley Yakeley)
Date: Wed Feb  7 02:13:04 2007
Subject: Haddock GADTs Hack
Message-ID: <eqbuf8$83m$1@sea.gmane.org>

Included is a hack to allow haddock to parse GADTs. There are two 
problems with it:

1. I don't think you can add doc comments to the constructors.

2. The shown types are wrong: the whole type of the constructor is shown 
as if it were the type of a single argument. Fixing this will presumably 
involve adding another constructor to HsConDecl to represent GADT 
constructors.

It wouldn't be appropriate to release haddock in this state, but I think 
it's helpful for those of us who could get no doc at all just because we 
have a GADT in our code.

-- 
Ashley Yakeley
Seattle, WA
-------------- next part --------------

New patches:

[hack to parse GADTs, though with incorrect constructor types
Ashley Yakeley <ashley@semantic.org>**20070207070109] {
hunk ./src/HsParser.ly 480
+> 	  | 'where' gadtconstrlist    { addConDocs $2 Nothing }
hunk ./src/HsParser.ly 497
+> gadtconstrlist :: { [HsConDecl] }
+>	: '{' gadtconstrs '}'			{ $2 }
+>	|     layout_on  gadtconstrs close	{ $2 }
+
+> gadtconstrs :: { [HsConDecl] }
+>	: gadtconstr ';' gadtconstrs		{ $1 : $3 }
+>	| ';' gadtconstrs			{ $2 }
+>	| gadtconstr				{ [$1] }
+>	| {- empty -}			{ [] }
+
+> gadtconstr :: { HsConDecl }
+>	: con srcloc '::' ctypedoc	{ HsConDecl $2 $1 [] [] [HsUnBangedTy $4] Nothing }
+
}

Context:

[infix type op precedence tweak, ppHsNameAsVar 
Conal Elliott <conal@conal.net>**20070115171157] 
[tweaked tyvarop precedence
Conal Elliott <conal@conal.net>**20070110002300] 
[added infix type operators
Conal Elliott <conal@conal.net>**20070105172038] 
[Make the search box in a form so that enter does the default search
Neil Mitchell <http://www.cs.york.ac.uk/~ndm/>**20070112125817] 
[Make the max number of results 75 instead of 50, to allow map searching in the base library to work
Neil Mitchell <http://www.cs.york.ac.uk/~ndm/>**20070112122501] 
[Rewrite much of the index searching code, previously was too slow to execute on the base library with IE, the new version guarantees less than O(log n) operations be performed, where n is the number in the list (before was always O(n))
Neil Mitchell <http://www.cs.york.ac.uk/~ndm/>**20070112121746] 
[Make the index be in case-insensitive alphabetic order
Neil Mitchell <http://www.cs.york.ac.uk/~ndm/>**20070111185143] 
[Change from tabs to spaces in the ppHtmlIndex function
Neil Mitchell <http://www.cs.york.ac.uk/~ndm/>**20070111182244] 
[Delete more stuff that is no longer required
Neil Mitchell <http://www.cs.york.ac.uk/~ndm/>**20070111182119] 
[Delete dead code, now there is only one index page
Neil Mitchell <http://www.cs.york.ac.uk/~ndm/>**20070111181746] 
[Add searching on the index page
Neil Mitchell <http://www.cs.york.ac.uk/~ndm/>**20070111170709] 
[Never do spliting index files into many
Neil Mitchell <http://www.cs.york.ac.uk/~ndm/>**20070111154115] 
[add test for blank lines inside @...@ code block
Simon Marlow <simonmar@microsoft.com>**20070109131444] 
[allow blank lines inside a @...@ code block
Simon Marlow <simonmar@microsoft.com>**20070109131434] 
[Fix up a case of extra vertical space after a code block
Simon Marlow <simonmar@microsoft.com>**20070105111341
 
 
] 
[TODO: do something better about re-exported symbols from another package
Simon Marlow <simonmar@microsoft.com>**20061215155200] 
[fix <<URL>> image markup
Simon Marlow <simonmar@microsoft.com>**20061208100637] 
[add todo item for --maintainer
Simon Marlow <simonmar@microsoft.com>**20061206160507] 
[fix --use-package error message
Simon Marlow <simonmar@microsoft.com>**20061013105135] 
[Cabal's sdist does not generate "-src.tar.gz" files, but ".tar.gz" ones
sven.panne@aedion.de**20061012152823] 
[Rename haddock.js to haddock-util.js
Simon Marlow <simonmar@microsoft.com>**20061011141737
 haddock.js will be run automatically by Windows when you type
 'haddock' if it is found on the PATH, so rename to avoid confusion.
 Spotted by Adrian Hey.
] 
[TAG 0.8 release
Simon Marlow <simonmar@microsoft.com>**20061010122403] 
Patch bundle hash:
4e32d45ab20492317a114d712a71c3295c6975d3
From simonpj at microsoft.com  Wed Feb  7 03:42:27 2007
From: simonpj at microsoft.com (Simon Peyton-Jones)
Date: Wed Feb  7 03:37:02 2007
Subject: Haddock GADTs Hack
In-Reply-To: <eqbuf8$83m$1@sea.gmane.org>
References: <eqbuf8$83m$1@sea.gmane.org>
Message-ID: <DCA83D5F3861C941808187D4D38787500154B3EC04@EA-EXMSG-C312.europe.corp.microsoft.com>

Great stuff.   However, David Waern's SoC project is very nearly at the point where he can generate Haddock for anything GHC understands; he's using GHC itself as the front end.

He's recently added the rendering code for GADTs I think.  I think he's probably planning a release shortly.  David?

Meanwhile Ashley's hack may well prove useful.

Simon


| -----Original Message-----
| From: haskelldoc-bounces@haskell.org [mailto:haskelldoc-bounces@haskell.org] On Behalf Of Ashley
| Yakeley
| Sent: 07 February 2007 07:18
| To: haskelldoc@haskell.org
| Subject: Haddock GADTs Hack
|
| Included is a hack to allow haddock to parse GADTs. There are two
| problems with it:
|
| 1. I don't think you can add doc comments to the constructors.
|
| 2. The shown types are wrong: the whole type of the constructor is shown
| as if it were the type of a single argument. Fixing this will presumably
| involve adding another constructor to HsConDecl to represent GADT
| constructors.
|
| It wouldn't be appropriate to release haddock in this state, but I think
| it's helpful for those of us who could get no doc at all just because we
| have a GADT in our code.
|
| --
| Ashley Yakeley
| Seattle, WA
From davve at dtek.chalmers.se  Wed Feb  7 05:48:40 2007
From: davve at dtek.chalmers.se (David Waern)
Date: Wed Feb  7 05:43:15 2007
Subject: Fwd: Haddock GADTs Hack
References: <mailman.37966.1170844510.2856.haskelldoc@haskell.org>
Message-ID: <047A65F3-484C-4E93-8810-F5A9EB17CFD2@dtek.chalmers.se>

Forwarding since my first post was rejected:

>
> Fr?n: David Waern <davve@dtek.chalmers.se>
> Datum: onsdag 7 feb 2007 11.40.36 GMT+01:00
> Till: Simon Peyton-Jones <simonpj@microsoft.com>
> Kopia: Ashley Yakeley <ashley@semantic.org>,  
> "haskelldoc@haskell.org" <haskelldoc@haskell.org>
> ?mne: Re: Haddock GADTs Hack
>
>
>
> 7 feb 2007 kl. 09.42 skrev Simon Peyton-Jones:
>
>> Great stuff.   However, David Waern's SoC project is very nearly  
>> at the point where he can generate Haddock for anything GHC  
>> understands; he's using GHC itself as the front end.
>>
>> He's recently added the rendering code for GADTs I think.  I think  
>> he's probably planning a release shortly.  David?
>>
>> Meanwhile Ashley's hack may well prove useful.
>>
>> Simon
>
> Hi,
>
> It's hard for me to make a release when GHC 6.8 is not out. But  
> I'll try to come up with some wiki page that describes Haddock-GHC  
> and how to use it with GHC HEAD.
>
> /David
>
>

From ashley at semantic.org  Wed Feb  7 15:40:17 2007
From: ashley at semantic.org (Ashley Yakeley)
Date: Wed Feb  7 15:35:05 2007
Subject: Fwd: Haddock GADTs Hack
In-Reply-To: <047A65F3-484C-4E93-8810-F5A9EB17CFD2@dtek.chalmers.se>
References: <mailman.37966.1170844510.2856.haskelldoc@haskell.org>
	<047A65F3-484C-4E93-8810-F5A9EB17CFD2@dtek.chalmers.se>
Message-ID: <eqddfi$rsm$1@sea.gmane.org>

David Waern wrote:

>> It's hard for me to make a release when GHC 6.8 is not out. But I'll 
>> try to come up with some wiki page that describes Haddock-GHC and how 

I definitely think using the same parser for GHC and Haddock is the way 
to go. If GHC can compile it, Haddock ought to be able to document it.

-- 
Ashley Yakeley