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? 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. I should note that I create haddock docs using 'cabal haddock' instead of calling haddock directly. Best regards, Christiaan
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.
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.
It never came to mind that '^' was the actual culprit :-) Now that I know that it's a (potential) bug, I'll just keep my eye on ghc-commit and wait for the bugfix. I'm used to running ghc-HEAD anyway. Also, is it not possible to update my haddock seperate from GHC? -- Christiaan
On 10/04/14 17:52, Christiaan Baaij wrote:
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.
It never came to mind that '^' was the actual culprit :-) Now that I know that it's a (potential) bug, I'll just keep my eye on ghc-commit and wait for the bugfix. I'm used to running ghc-HEAD anyway.
Ah. I'll probably push out a fix tomorrow then and you can grab that.
Also, is it not possible to update my haddock seperate from GHC?
You should be able to simply cabal install haddock as long as you are using the GHC version it expects. For Haddock HEAD (to-be 2.15.0), you need GHC 7.9: you can just go to utils/haddock in the GHC tree and run cabal install there (or clone outside of the tree or whatever). For the 2.14.x releases, we require 7.8.x.
-- Christiaan
-- Mateusz K.
On 10/04/14 17:52, Christiaan Baaij wrote:
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.
It never came to mind that '^' was the actual culprit :-) Now that I know that it's a (potential) bug, I'll just keep my eye on ghc-commit and wait for the bugfix. I'm used to running ghc-HEAD anyway.
Also, is it not possible to update my haddock seperate from GHC?
-- Christiaan
For those not idling #ghc or stumbling upon this in 7 years, I have fixed the problem and it should ship with 2.14.3 which should in turn ship with 7.8.3. -- Mateusz K.
participants (2)
-
Christiaan Baaij -
Mateusz Kowalczyk