jon.recoil.org
this repo has no description
1(** Parser for ocamldoc formatted comments. *)
2
3type t
4(** [type t] is the result of parsing. *)
5
6val parse_comment : location:Lexing.position -> text:string -> t
7(** [parse_comment ~location ~text] parses [text] as an ocamldoc formatted
8 string. The parser will try to recover from any invalid syntax encountered,
9 and therefore this will always produce a result without raising exceptions
10 with zero or more warnings. The location passed in should represent the
11 start of the {i content} of the documentation comment - so for a line such
12 as
13 {[
14 (** A comment starting in the first column (0) *)
15 ]}
16 the location should represent the space immediately before the [A], so the
17 in the 4th column (e.g. [{... pos_bol=0; pos_cnum=3 }]) *)
18
19module Ast = Ast
20module Loc = Loc
21
22(** Warnings produced during parsing. *)
23module Warning : sig
24 type t = Warning.t = { location : Loc.span; message : string }
25 (** Warnings are represented as record containing the human-readable text of
26 the warning alongside the location of the offending text in the source *)
27
28 val pp : Format.formatter -> t -> unit
29 (** Pretty printer for {!t} *)
30
31 val to_string : t -> string
32 (** [to_string] will format the location and warning as text to be printed. *)
33end
34
35val warnings : t -> Warning.t list
36(** Extract any warnings from the parser result. *)
37
38val ast : t -> Ast.t
39(** Extract the {!Ast.t} from the parser result. *)
40
41val position_of_point : t -> Loc.point -> Lexing.position
42(** Helper function to turn the internal representation of positions back into
43 the usual representation in the Lexing module. Note that this relies on the
44 information passed in {!parse_comment}, and hence requires the result of
45 that call in addition to the {!Loc.point} being converted. *)
46
47val codeblock_content : Loc.span -> string -> string * Warning.t list
48(** Process the content of a code block, following the rules described
49 {{!/odoc/page-odoc_for_authors.indentation_code_blocks}here}. To achieve this, it
50 needs the location of the code block (including the separators) and the raw
51 content of the code block. For instance, with the following code block:
52
53 {delim@ocaml[
54 {[
55 hello
56 ]}
57 ]delim}
58
59 We can go from the raw content ["\n hello\n "] to the processed content
60 [" hello"] with:
61 {[
62 match codeblock.value with
63 | `Code_block { content; _ } ->
64 codeblock_content codeblock.location content.value
65 ]}
66
67 Also returns a list of warnings, eg if the content is not appropriately
68 indented. *)
69
70val verbatim_content : Loc.span -> string -> string * Warning.t list
71(** Similar to {!codeblock_content} but for verbatims. *)