I often hit such errors: parse error on input ‘-- ^ my doc-string is here’ when generate Haddock documentation. This happens on line like: instance Something UTCTime where some a = blahBlah -- ^ my doc-string is here Sometimes such doc-strings are passing, sometimes - not. I can understand what is the reason. Is there some rule how to format such kind of doc-strings? === Cheers, Paul
On Thu, Oct 26, 2017 at 01:03:56PM +0300, Baa wrote:
Sometimes such doc-strings are passing, sometimes - not. I can understand what is the reason. Is there some rule how to format such kind of doc-strings?
Hello Paul, can you provide an example of a docstring which makes Haddock choke?
@Francesco Ariis: instance Conversion UTCTime where aspS a = round $ 1E12 * utcTimeToPOSIXSeconds a -- ^as time period from 1970-1-1 frompS a = posixSecondsToUTCTime $ fromInteger $ (round $ d/1E12) -- ^from time period from 1970-1-1 where d = fromInteger a :: Double @Sylvain: sure I can remove "^", but in this case in will be comment, not doc-string; am I right, or? I want to add this string to Haddock generated documentation. So, I see that sometimes no problem with "^..."-style docstrings (attached? or how is it called correctly?). But sometimes their lead to errors.
On Thu, Oct 26, 2017 at 01:03:56PM +0300, Baa wrote:
Sometimes such doc-strings are passing, sometimes - not. I can understand what is the reason. Is there some rule how to format such kind of doc-strings?
Hello Paul, can you provide an example of a docstring which makes Haddock choke? _______________________________________________ Beginners mailing list Beginners@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/beginners
On Thu, Oct 26, 2017 at 02:11:10PM +0300, Baa wrote:
@Francesco Ariis:
instance Conversion UTCTime where aspS a = round $ 1E12 * utcTimeToPOSIXSeconds a -- ^as time period from 1970-1-1 frompS a = posixSecondsToUTCTime $ fromInteger $ (round $ d/1E12) -- ^from time period from 1970-1-1 where d = fromInteger a :: Double
-- ^ is meant to be put after a function *declaration* iirc. Try to add signatures to your instance as instance Foo Bar where fa :: Int -> a -- ^ some comment fa x = undefined fb :: String -> a -- ^ some more comment fb x = undefined and let us know if it fixed the problem.
@Francesco: I tried it (added extension InstanceSigs, added "^.."-style docstring), nothing changed. So, may be docstrings in instances are impossible at whole? May be it makes sense... May be they should be documented in its classes instead?
On Thu, Oct 26, 2017 at 02:11:10PM +0300, Baa wrote:
@Francesco Ariis:
instance Conversion UTCTime where aspS a = round $ 1E12 * utcTimeToPOSIXSeconds a -- ^as time period from 1970-1-1 frompS a = posixSecondsToUTCTime $ fromInteger $ (round $ d/1E12) -- ^from time period from 1970-1-1 where d = fromInteger a :: Double
-- ^ is meant to be put after a function *declaration* iirc. Try to add signatures to your instance as
instance Foo Bar where fa :: Int -> a -- ^ some comment fa x = undefined fb :: String -> a -- ^ some more comment fb x = undefined
and let us know if it fixed the problem. _______________________________________________ Beginners mailing list Beginners@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/beginners
On Thu, Oct 26, 2017 at 02:58:43PM +0300, Baa wrote:
@Francesco:
I tried it (added extension InstanceSigs, added "^.."-style docstring), nothing changed. So, may be docstrings in instances are impossible at whole? May be it makes sense... May be they should be documented in its classes instead?
Mhhh indeed you are correct, I tried to replicate and while haddock doesn't complain, it doesn't output anything for the implemented functions. Maybe a workaround could be: -- | Prova instance Fun Foo where fun :: a fun = undefined This will put text on the right of the /instance declaration/.
@Francesco: yes, it is. OK, it's a workaround :) Thank you!
On Thu, Oct 26, 2017 at 02:58:43PM +0300, Baa wrote:
@Francesco:
I tried it (added extension InstanceSigs, added "^.."-style docstring), nothing changed. So, may be docstrings in instances are impossible at whole? May be it makes sense... May be they should be documented in its classes instead?
Mhhh indeed you are correct, I tried to replicate and while haddock doesn't complain, it doesn't output anything for the implemented functions.
Maybe a workaround could be:
-- | Prova instance Fun Foo where fun :: a fun = undefined
This will put text on the right of the /instance declaration/. _______________________________________________ Beginners mailing list Beginners@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/beginners
Just remove the `^` character. `|` and `^` (attaching the comment to the next/previous entity) can't be used everywhere. On 26/10/2017 12:03, Baa wrote:
I often hit such errors:
parse error on input ‘-- ^ my doc-string is here’
when generate Haddock documentation. This happens on line like:
instance Something UTCTime where some a = blahBlah -- ^ my doc-string is here
Sometimes such doc-strings are passing, sometimes - not. I can understand what is the reason. Is there some rule how to format such kind of doc-strings?
=== Cheers, Paul _______________________________________________ Beginners mailing list Beginners@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/beginners
participants (3)
-
Baa -
Francesco Ariis -
Sylvain Henry