What's wrong with Haddock?!

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
8 messages Options
Baa
Reply | Threaded
Open this post in threaded view
|

What's wrong with Haddock?!

Baa
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
[hidden email]
http://mail.haskell.org/cgi-bin/mailman/listinfo/beginners
Reply | Threaded
Open this post in threaded view
|

Re: What's wrong with Haddock?!

Francesco Ariis
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
[hidden email]
http://mail.haskell.org/cgi-bin/mailman/listinfo/beginners
Reply | Threaded
Open this post in threaded view
|

Re: What's wrong with Haddock?!

Sylvain Henry-2
In reply to this post by Baa
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
> [hidden email]
> http://mail.haskell.org/cgi-bin/mailman/listinfo/beginners

_______________________________________________
Beginners mailing list
[hidden email]
http://mail.haskell.org/cgi-bin/mailman/listinfo/beginners
Baa
Reply | Threaded
Open this post in threaded view
|

Re: What's wrong with Haddock?!

Baa
In reply to this post by Francesco Ariis
@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
> [hidden email]
> http://mail.haskell.org/cgi-bin/mailman/listinfo/beginners

_______________________________________________
Beginners mailing list
[hidden email]
http://mail.haskell.org/cgi-bin/mailman/listinfo/beginners
Reply | Threaded
Open this post in threaded view
|

Re: What's wrong with Haddock?!

Francesco Ariis
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
[hidden email]
http://mail.haskell.org/cgi-bin/mailman/listinfo/beginners
Baa
Reply | Threaded
Open this post in threaded view
|

Re: What's wrong with Haddock?!

Baa
@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
> [hidden email]
> http://mail.haskell.org/cgi-bin/mailman/listinfo/beginners

_______________________________________________
Beginners mailing list
[hidden email]
http://mail.haskell.org/cgi-bin/mailman/listinfo/beginners
Reply | Threaded
Open this post in threaded view
|

Re: What's wrong with Haddock?!

Francesco Ariis
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
[hidden email]
http://mail.haskell.org/cgi-bin/mailman/listinfo/beginners
Baa
Reply | Threaded
Open this post in threaded view
|

Re: What's wrong with Haddock?!

Baa
@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
> [hidden email]
> http://mail.haskell.org/cgi-bin/mailman/listinfo/beginners

_______________________________________________
Beginners mailing list
[hidden email]
http://mail.haskell.org/cgi-bin/mailman/listinfo/beginners