On 10/04/14 17:22, Christiaan Baaij wrote:
Hello list,
I have two questions regarding proper markup for my haddock documentation. I'm using the latest released haddock, version 2.14.2.
The first is about deprecation pragma's and operators usint '<' and '>' I have the following deprecation message:
{-# DEPRECATED Comp "Use 'Applicative' interface and ('<^>') instead" #-}
Haddock however generates the following: http://christiaanb.github.io/clash-prelude/CLaSH-Prelude.html#t:Comp
Where 'Applicative' gets a proper link to the applicative type class... but '<^>' is translated to a link to '^'... which is a page that doesn't exists.
I can get haddock to not generate a link using:
{-# DEPRECATED Comp "Use 'Applicative' interface and ('\\<^\\>') instead" #-}
But that's unwanted, as those backslashes show up in GHC(i) messages. So: how do I get haddock to not parse my '<^>' operator as a link/URL?
Hm, strange, technically we parse identifiers first and links second so this should work without a problem unless Haddock doesn't recognise it as an identifier. I actually now notice in the parser that we don't consider ^ to be a valid symbol so that's probably the culprit! Good catch, if that's actually the case here then you can expect it to be fixed in the next release, perhaps with 7.8.3 or something. Unfortunately the way we do identifier parsing now is that we slurp everything that looks like a valid identifier and afterwards we ask GHC to actually tell us if it's it's something we know about. It seems like a bug caused by me not being careful when reading the relevant part of the report, deepest apologies! I do wish we had a better way of parsing these identifiers but I can't think of one.
My second question is again about getting links to operators in general. If you take a look at, e.g., http://hackage.haskell.org/package/base-4.7.0.0/docs/Control-Applicative.htm... You can see that proper documentation links are generated to the '<*>' and such operators. However, if you take a look at the documention I tried to generate for my library: http://christiaanb.github.io/clash-prelude/CLaSH-Signal-Implicit.html#v:-60-... You can see that the referenced '^>' operator does not get a proper link. So my question: how do I get haddock to create proper links for my referenced operators.
Sounds like it's the same issue.
I should note that I create haddock docs using 'cabal haddock' instead of calling haddock directly.
Best regards,
Christiaan
_______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
-- Mateusz K.