parseDocs's type about documentalist

[jspahrsummers]

It would be helpful to include some kind of diagnostic information, since otherwise it'll be very unclear why documentation wasn't generated for a comment.

[mxswd]

Ah I see. Yeah.

[jspahrsummers]

Well, I think the thrust of this is still valid. Comment parsing should probably not be fatal, so your other idea of parameterizing with an Either CommentParseException DocBlock makes sense.

[mxswd]

We could make DocBlock's summary a Maybe.
Then if you have no comments, you still get a DocBlock where all the fields are mempty.

data DocBlock = DocBlock
    { summary :: Maybe Paragraph
    , description :: [Paragraph]
    , parameters :: [DocParam]
    , example :: Maybe Code
    , result :: Maybe Result
    } deriving Eq

[jspahrsummers]

That still doesn't really solve the problem I alluded to. We need to notify the user somehow when parsing a specific comment fails.

[mxswd]

Assuming all comment parsing exceptions are non fatal (I think this is ok);
parseDocs can return a Package (Either CommentParseException DocBlock).
Then your main function must have some function to map it to Package (Maybe DocBlock) so you can put it into write :: Package (Maybe DocBlock) -> w ().

Something like:

showErrors :: Either CommentParseException DocBlock -> IO (Maybe DocBlock)
showErrors (Left e) = hPutStrLn stderr (show e) >> return Nothing
showErrors (Right x) = return $ Just x

The reason I brought up it as an instance of Monoid, is that function would be:

showErrors (Left x) = hPutStrLn stderr (show x) >> return mempty -- shows the CommentParseException
showErrors (Right x) = return x

And write would be Package DocBlock -> w ()

Also this changes #39, because this traversal is the Traversable one, so I guess we should have both the current one we have and a more refined version for the type.

[mxswd]

I thought about it a bit more, and when you are writing the docs, you want to know if it is Nothing (i.e. no comments were on that function), so Either CommentParseException DocBlock -> IO (Maybe DocBlock) is good. And lets not do a Monoid.