Nabble - Haskell - HaskellDoc

ANN: Haddock version 2.2.1

2008-08-04T04:43:23Z

--------------------------------------------
-- Haddock 2.2.1
--------------------------------------------

A new version of Haddock, the Haskell documentation tool, is out.

The homepage will be updated soon, containing a windows binary release.

Please use the bug tracker to submit bug reports and feature requests.

--------------------------------------------
-- Changes since version 2.1.0
--------------------------------------------

* Support for GHC 6.8.3

* The Hoogle backend is back

* Show associated types in the documentation for class declarations

* Show type family declarations

* Show type equality predicates

* Major bug fixes (#1 and #44)

* It is no longer required to specify the path to GHC's lib dir

* Remove unnecessary parenthesis in type signatures

* Minor bug fixes

--------------------------------------------
-- Links
--------------------------------------------

Homepage:
http://www.haskell.org/haddock

Hackage page:
http://hackage.haskell.org/cgi-bin/hackage-scripts/package/haddock-2.2.1

Bugtracker and wiki:
http://trac.haskell.org/haddock

Mailing list:
haskelldoc@...

Code repository:
http://code.haskell.org/haddock

--------------------------------------------
-- Details
--------------------------------------------

This release contains experimental and incomplete support for GHC's
Type Families extension. We have basic support for rendering of type
family declarations and associated types in the documentation.
Type/Data instances are not shown in the documentation at all, and
associated types are not shown for class instances. Feedback is
appreciated, especially for ideas of how to render type family
instances. Use either the bugtracker, or send a mail to the mailing
list.

We have also got the Hoogle backend back, thanks to Neil Mitchell! The
plan is to be compatible with the upcoming pre-release of Hoogle 4,
which is being developed by Neil as a Summer of Code project.

--------------------------------------------
-- Get Involved
--------------------------------------------

Haddock is an important project, as it is part of the Haskell
infrastructure core. The code base is gradually becoming easier to
read, better documented and more stable, but more work is needed. To
get involved, start by grabbing the code at

http://code.haskell.org/haddock

then take a look at the bug and feature tracker at

http://trac.haskell.org/haddock

for things to work on.

David
_______________________________________________
HaskellDoc mailing list
HaskellDoc@...
http://www.haskell.org/mailman/listinfo/haskelldoc

RE: Type Families in Haddock

2008-07-04T06:30:41Z

That would be fabulous.

| -----Original Message-----
| From: haskelldoc-bounces@... [mailto:haskelldoc-bounces@...] On Behalf Of David Waern
| Sent: 02 July 2008 08:53
| To: cvs-ghc@...; haskelldoc@...
| Subject: Type Families in Haddock
|
| Hi,
|
| I'm going to add Type Families support to the Haddock HTML backend.
| What would be the best way to do it? I'm thinking it could work
| similar to how classes and instances are currently rendered, so that
| type/data/newtype instances are collected and attached to type family
| declarations. Is this too simplistic? Should we render
| type/data/newtype instances as separate entities in the module
| documentation instead (and perhaps do the same thing with class
| instances)?
|
| Currently, when packages export instances that belong to classes from
| other packages, those instances are not documented anywhere. An
| advantage of having instances as separate entities in the exporting
| module documentation is that no instances are "lost".
|
| David
| _______________________________________________
| HaskellDoc mailing list
| HaskellDoc@...
| http://www.haskell.org/mailman/listinfo/haskelldoc

_______________________________________________
HaskellDoc mailing list
HaskellDoc@...
http://www.haskell.org/mailman/listinfo/haskelldoc

Re: Type Families in Haddock

2008-07-03T18:44:08Z

Hi David,

> I'm going to add Type Families support to the Haddock HTML backend.

Great!

> What would be the best way to do it? I'm thinking it could work
> similar to how classes and instances are currently rendered, so that
> type/data/newtype instances are collected and attached to type family
> declarations. Is this too simplistic? Should we render
> type/data/newtype instances as separate entities in the module
> documentation instead (and perhaps do the same thing with class
> instances)?
>
> Currently, when packages export instances that belong to classes from
> other packages, those instances are not documented anywhere. An
> advantage of having instances as separate entities in the exporting
> module documentation is that no instances are "lost".

I think the basic idea to treat class and family declarations and
instances in essentially the same way is a good.

Losing instances is of course bad for both classes and families. I
think it still makes sense to bunch the instances of one class or one
family up in a block. In fact, for type synonyms instances, there are
many applications, where this is really important for readability.
Please also remember that family declarations and instances can be
nested in class declarations and instances (as associated types).

Manuel

_______________________________________________
HaskellDoc mailing list
HaskellDoc@...
http://www.haskell.org/mailman/listinfo/haskelldoc

Re: Type Families in Haddock

2008-07-02T10:47:42Z

2008/7/2 Don Stewart <dons@...>:

> david.waern:
>> Hi,
>>
>> I'm going to add Type Families support to the Haddock HTML backend.
>> What would be the best way to do it? I'm thinking it could work
>> similar to how classes and instances are currently rendered, so that
>> type/data/newtype instances are collected and attached to type family
>> declarations. Is this too simplistic? Should we render
>> type/data/newtype instances as separate entities in the module
>> documentation instead (and perhaps do the same thing with class
>> instances)?
>>
>> Currently, when packages export instances that belong to classes from
>> other packages, those instances are not documented anywhere. An
>> advantage of having instances as separate entities in the exporting
>> module documentation is that no instances are "lost".
>>
>
> Please go for it! I need type families support for the uvector
> documentation to build.
>
> http://hackage.haskell.org/packages/archive/uvector/0.1/logs/failure/ghc-6.8

Yes, I didn't bother to add proper error messages for unsupported
syntax, so that's why some packages that use e.g. type families just
die with pattern matching failures. I'm adding support for more syntax
now, and I'll try to add proper error messages if I come across
something that won't be supported.

David
_______________________________________________
HaskellDoc mailing list
HaskellDoc@...
http://www.haskell.org/mailman/listinfo/haskelldoc

Type Families in Haddock

2008-07-02T00:52:34Z

Hi,

I'm going to add Type Families support to the Haddock HTML backend.
What would be the best way to do it? I'm thinking it could work
similar to how classes and instances are currently rendered, so that
type/data/newtype instances are collected and attached to type family
declarations. Is this too simplistic? Should we render
type/data/newtype instances as separate entities in the module
documentation instead (and perhaps do the same thing with class
instances)?

Currently, when packages export instances that belong to classes from
other packages, those instances are not documented anywhere. An
advantage of having instances as separate entities in the exporting
module documentation is that no instances are "lost".

David
_______________________________________________
HaskellDoc mailing list
HaskellDoc@...
http://www.haskell.org/mailman/listinfo/haskelldoc

Re: Haddock 2.0.0.0 Bug: Doesn't Like {;}-Style Code

2008-05-14T04:42:05Z

> I wrote:
>> Try running haddock on this:
>>
>> module HaddockBug where
>> {
>> -- |The 'square' function squares an integer.
>> square :: Int -> Int;
>> square x = x * x;
>> }
>>
>> $ haddock -B /usr/lib/ghc-6.8.2/ HaddockBug.hs
>>
>> HaddockBug.hs:4:0: parse error on input `square'
>> haddock: Failed to load all needed modules
>>
>> It works fine if you remove the haddock comment...
>
> I discovered a work-around: put a semicolon after the haddock comment.
>
> module HaddockBug where
> {
> -- |The 'square' function squares an integer.
> ;
> square :: Int -> Int;
> square x = x * x;
> }
>
> --
> Ashley Yakeley
> Seattle, WA
>

Thanks for the report. This is a known bug though, and it's due to the
fact that Haddock comments are handled just like any other declaration in
the GHC grammar. This should be changed, so that the placement of Haddock
comments doesn't depend on layout, but I never got around to fix it during
the Summer of Code project. I will update the TODO file to include this
bug.

David

_______________________________________________
HaskellDoc mailing list
HaskellDoc@...
http://www.haskell.org/mailman/listinfo/haskelldoc

Haddock 2.0.0.0 Bug: Doesn't Like {;}-Style Code

2008-05-08T03:00:35Z

Try running haddock on this:

module HaddockBug where
{
-- |The 'square' function squares an integer.
square :: Int -> Int;
square x = x * x;
}

$ haddock -B /usr/lib/ghc-6.8.2/ HaddockBug.hs

HaddockBug.hs:4:0: parse error on input `square'
haddock: Failed to load all needed modules

It works fine if you remove the haddock comment...

--
Ashley Yakeley
Seattle, WA

_______________________________________________
HaskellDoc mailing list
HaskellDoc@...
http://www.haskell.org/mailman/listinfo/haskelldoc

Re: Fwd: Haddock GADTs Hack

2007-02-07T12:40:17Z

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

_______________________________________________
HaskellDoc mailing list
HaskellDoc@...
http://www.haskell.org/mailman/listinfo/haskelldoc

Fwd: Haddock GADTs Hack

2007-02-07T02:48:40Z

Forwarding since my first post was rejected:

>
> Från: David Waern <davve@...>
> Datum: onsdag 7 feb 2007 11.40.36 GMT+01:00
> Till: Simon Peyton-Jones <simonpj@...>
> Kopia: Ashley Yakeley <ashley@...>,
> "haskelldoc@..." <haskelldoc@...>
> Ä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
>
>

_______________________________________________
HaskellDoc mailing list
HaskellDoc@...
http://www.haskell.org/mailman/listinfo/haskelldoc

RE: Haddock GADTs Hack

2007-02-07T00:42:27Z

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@... [mailto:haskelldoc-bounces@...] On Behalf Of Ashley
| Yakeley
| Sent: 07 February 2007 07:18
| To: haskelldoc@...
| 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
_______________________________________________
HaskellDoc mailing list
HaskellDoc@...
http://www.haskell.org/mailman/listinfo/haskelldoc

Haddock GADTs Hack

2007-02-06T23:17:59Z

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

New patches:

[hack to parse GADTs, though with incorrect constructor types
Ashley Yakeley <ashley@...>**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@...>**20070115171157]
[tweaked tyvarop precedence
Conal Elliott <conal@...>**20070110002300]
[added infix type operators
Conal Elliott <conal@...>**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@...>**20070109131444]
[allow blank lines inside a @...@ code block
Simon Marlow <simonmar@...>**20070109131434]
[Fix up a case of extra vertical space after a code block
Simon Marlow <simonmar@...>**20070105111341

]
[TODO: do something better about re-exported symbols from another package
Simon Marlow <simonmar@...>**20061215155200]
[fix <<URL>> image markup
Simon Marlow <simonmar@...>**20061208100637]
[add todo item for --maintainer
Simon Marlow <simonmar@...>**20061206160507]
[fix --use-package error message
Simon Marlow <simonmar@...>**20061013105135]
[Cabal's sdist does not generate "-src.tar.gz" files, but ".tar.gz" ones
sven.panne@...**20061012152823]
[Rename haddock.js to haddock-util.js
Simon Marlow <simonmar@...>**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@...>**20061010122403]
Patch bundle hash:
4e32d45ab20492317a114d712a71c3295c6975d3

_______________________________________________
HaskellDoc mailing list
HaskellDoc@...
http://www.haskell.org/mailman/listinfo/haskelldoc

Re: Haddock 0.8 question

2006-03-03T06:57:13Z

J. Garrett Morris wrote:
> Greetings, list,

I'm not sure how many people read this list...

> I just downloaded and compiled Haddock 0.8. I still seem to be
> running into a couple of issues, namely:
>
> * The parser gags on the identifier ##,

Do you mean (##)? This would be because Haddock is parsing GHC
extensions by default. Insert spaces like this: ( ## ).

> * and on generalized algebraic data types.
>
> Am I missing an obvious configuration switch, workaround, etc.?

GADTs aren't currently supported by Haddock, sorry.

Cheers,
Simon
_______________________________________________
HaskellDoc mailing list
HaskellDoc@...
http://www.haskell.org/mailman/listinfo/haskelldoc

Haddock 0.8 question

2006-03-01T13:12:54Z

Greetings, list,

I just downloaded and compiled Haddock 0.8. I still seem to be
running into a couple of issues, namely:

* The parser gags on the identifier ##,
* and on generalized algebraic data types.

Am I missing an obvious configuration switch, workaround, etc.?

/g
_______________________________________________
HaskellDoc mailing list
HaskellDoc@...
http://www.haskell.org/mailman/listinfo/haskelldoc