Expose parser internals and add Parser.parse_comment_raw

[Julow]

This PR exposes the internal modules of the parser.

I figured that Parser_.Ast is a bit simpler than Model.Comment and a lot simpler to obtain.
It also contains more informations (eg. heading labels)

I also add Parser.parse_comment_raw that returns an Ast.docs.

[aantron]

a lot simpler to obtain

What would make Model.Comment easier for you to obtain?

It also contains more informations (eg. heading labels)

I suggest to retain any information you need in Model.Comment, rather than exposing another data representation.

[Julow]

By simpler I meant it's no longer needed to construct the containing_definition argument with dummy values.
I agree if it was only for heading labels, changing Model.Comment would be better. But I was hoping to continue simplifying the parser in later PR. In particular using a simpler representation for references in Parser.Ast.

I'm using Odoc in OCamlformat to reformat documentation comments. Currently, Odoc is quite hard to use and I'd like to improve this.

[jonludlam]

Ah, having to build a dummy argument to the function is definitely something we should fix.

I'm not quite sure I follow the argument about exposing Ast over Model.Comment - the heading labels are still there, aren't they? (admittedly embedded in an Identifier, so not quite so conveniently). I couldn't see anything else missing either.

[Julow]

The problem with heading labels is that they are not optional in Model.Comment and it's impossible to tell if it's present in the source or if it's a default value.
Also, I think an even simpler AST would be useful for user of the libraries that just want to parse comments.
For example, in ocaml-ppx/ocamlformat#721, I had to fight the AST to print references and a lot of comments are not formatted because of warnings that could be delayed until the semantics pass.

[jonludlam]

We could put the original text in the reference tag:

`Reference of Reference.t * string * link_content

and mark the headers with whether the label was generated or specified?

It doesn't seem totally unreasonable to me that ocamlformat only formats valid ocamldoc markup, to be honest, so long as we can surface the warnings to the user. It's a bit of an incentive to write the docs correctly :-)

[aantron]

Closing this PR, as I believe the discussion in #355 supersedes it.

[Julow]

Thanks for the reopen !

I rebased on master and changed the way the AST is exposed.

[aantron]

Looks good. Thanks for your patience and initiative!

[Julow]

Thanks !