forked from ocaml/ocaml
-
Notifications
You must be signed in to change notification settings - Fork 6
/
Copy pathdocstrings.mli
148 lines (102 loc) · 4.91 KB
/
docstrings.mli
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
(***********************************************************************)
(* *)
(* OCaml *)
(* *)
(* Leo White *)
(* *)
(* Copyright 1996 Institut National de Recherche en Informatique et *)
(* en Automatique. All rights reserved. This file is distributed *)
(* under the terms of the Q Public License version 1.0. *)
(* *)
(***********************************************************************)
(** (Re)Initialise all docstring state *)
val init : unit -> unit
(** Emit warnings for unattached and ambiguous docstrings *)
val warn_bad_docstrings : unit -> unit
(** {3 Docstrings} *)
(** Documentation comments *)
type docstring
(** Create a docstring *)
val docstring : string -> Location.t -> docstring
(** Get the text of a docstring *)
val docstring_body : docstring -> string
(** Get the location of a docstring *)
val docstring_loc : docstring -> Location.t
(** {3 Set functions}
These functions are used by the lexer to associate docstrings to
the locations of tokens. *)
(** Docstrings immediately preceding a token *)
val set_pre_docstrings : Lexing.position -> docstring list -> unit
(** Docstrings immediately following a token *)
val set_post_docstrings : Lexing.position -> docstring list -> unit
(** Docstrings not immediately adjacent to a token *)
val set_floating_docstrings : Lexing.position -> docstring list -> unit
(** Docstrings immediately following the token which precedes this one *)
val set_pre_extra_docstrings : Lexing.position -> docstring list -> unit
(** Docstrings immediately preceding the token which follows this one *)
val set_post_extra_docstrings : Lexing.position -> docstring list -> unit
(** {3 Items}
The {!docs} type represents documentation attached to an item. *)
type docs =
{ docs_pre: docstring option;
docs_post: docstring option; }
val empty_docs : docs
val docs_attr : docstring -> Parsetree.attribute
(** Convert item documentation to attributes and add them to an
attribute list *)
val add_docs_attrs : docs -> Parsetree.attributes -> Parsetree.attributes
(** Fetch the item documentation for the current symbol. This also
marks this documentation (for ambiguity warnings). *)
val symbol_docs : unit -> docs
val symbol_docs_lazy : unit -> docs Lazy.t
(** Fetch the item documentation for the symbols between two
positions. This also marks this documentation (for ambiguity
warnings). *)
val rhs_docs : int -> int -> docs
val rhs_docs_lazy : int -> int -> docs Lazy.t
(** Mark the item documentation for the current symbol (for ambiguity
warnings). *)
val mark_symbol_docs : unit -> unit
(** Mark as associated the item documentation for the symbols between
two positions (for ambiguity warnings) *)
val mark_rhs_docs : int -> int -> unit
(** {3 Fields and constructors}
The {!info} type represents documentation attached to a field or
constructor. *)
type info = docstring option
val empty_info : info
val info_attr : docstring -> Parsetree.attribute
(** Convert field info to attributes and add them to an
attribute list *)
val add_info_attrs : info -> Parsetree.attributes -> Parsetree.attributes
(** Fetch the field info for the current symbol. *)
val symbol_info : unit -> info
(** Fetch the field info following the symbol at a given position. *)
val rhs_info : int -> info
(** {3 Unattached comments}
The {!text} type represents documentation which is not attached to
anything. *)
type text = docstring list
val empty_text : text
val text_attr : docstring -> Parsetree.attribute
(** Convert text to attributes and add them to an attribute list *)
val add_text_attrs : text -> Parsetree.attributes -> Parsetree.attributes
(** Fetch the text preceding the current symbol. *)
val symbol_text : unit -> text
val symbol_text_lazy : unit -> text Lazy.t
(** Fetch the text preceding the symbol at the given position. *)
val rhs_text : int -> text
val rhs_text_lazy : int -> text Lazy.t
(** {3 Extra text}
There may be additional text attached to the delimiters of a block
(e.g. [struct] and [end]). This is fetched by the following
functions, which are applied to the contents of the block rather
than the delimiters. *)
(** Fetch additional text preceding the current symbol *)
val symbol_pre_extra_text : unit -> text
(** Fetch additional text following the current symbol *)
val symbol_post_extra_text : unit -> text
(** Fetch additional text preceding the symbol at the given position *)
val rhs_pre_extra_text : int -> text
(** Fetch additional text following the symbol at the given position *)
val rhs_post_extra_text : int -> text