1 (**************************************************************************)
2 (* *)
3 (* OCaml *)
4 (* *)
5 (* Maxence Guesdon, projet Cristal, INRIA Rocquencourt *)
6 (* *)
7 (* Copyright 2001 Institut National de Recherche en Informatique et *)
8 (* en Automatique. *)
9 (* *)
10 (* All rights reserved. This file is distributed under the terms of *)
11 (* the GNU Lesser General Public License version 2.1, with the *)
12 (* special exception on linking described in the file LICENSE. *)
13 (* *)
14 (**************************************************************************)
15
16 (** Interface to the information collected in source files. *)
17
18 (** The different kinds of element references. *)
19 type ref_kind = Odoc_types.ref_kind =
20 RK_module
21 | RK_module_type
22 | RK_class
23 | RK_class_type
24 | RK_value
25 | RK_type
26 | RK_extension
27 | RK_exception
28 | RK_attribute
29 | RK_method
30 | RK_section of text
31 | RK_recfield
32 | RK_const
33
34 and text_element = Odoc_types.text_element =
35 | Raw of string (** Raw text. *)
36 | Code of string (** The string is source code. *)
37 | CodePre of string (** The string is pre-formatted source code. *)
38 | Verbatim of string (** String 'as is'. *)
39 | Bold of text (** Text in bold style. *)
40 | Italic of text (** Text in italic. *)
41 | Emphasize of text (** Emphasized text. *)
42 | Center of text (** Centered text. *)
43 | Left of text (** Left alignment. *)
44 | Right of text (** Right alignment. *)
45 | List of text list (** A list. *)
46 | Enum of text list (** An enumerated list. *)
47 | Newline (** To force a line break. *)
48 | Block of text (** Like html's block quote. *)
49 | Title of int * string option * text
50 (** Style number, optional label, and text. *)
51 | Latex of string (** A string for latex. *)
52 | Link of string * text (** A reference string and the link text. *)
53 | Ref of string * ref_kind option * text option
54 (** A reference to an element. Complete name and kind.
55 An optional text can be given to display this text instead
56 of the element name.*)
57 | Superscript of text (** Superscripts. *)
58 | Subscript of text (** Subscripts. *)
59 | Module_list of string list
60 (** The table of the given modules with their abstract. *)
61 | Index_list (** The links to the various indexes (values, types, ...) *)
62 | Custom of string * text (** to extend \{foo syntax *)
63 | Target of string * string (** (target, code) : to specify code specific to a target format *)
64
65 (** A text is a list of [text_element]. The order matters. *)
66 and text = text_element list
67
68 (** The different forms of references in \@see tags. *)
69 type see_ref = Odoc_types.see_ref =
70 See_url of string
71 | See_file of string
72 | See_doc of string
73
74 (** Raised when parsing string to build a {!Odoc_info.text}
75 structure. [(line, char, string)] *)
76 exception Text_syntax of int * int * string
77
78 (** The information in a \@see tag. *)
79 type see = see_ref * text
80
81 (** Parameter name and description. *)
82 type param = (string * text)
83
84 (** Raised exception name and description. *)
85 type raised_exception = (string * text)
86
87 (** Information in a special comment
88 @before 3.12.0 \@before information was not present.
89 *)
90 type info = Odoc_types.info = {
91 i_desc : text option; (** The description text. *)
92 i_authors : string list; (** The list of authors in \@author tags. *)
93 i_version : string option; (** The string in the \@version tag. *)
94 i_sees : see list; (** The list of \@see tags. *)
95 i_since : string option; (** The string in the \@since tag. *)
96 i_before : (string * text) list ; (** the version number and text in \@before tag *)
97 i_deprecated : text option; (** The description text of the \@deprecated tag. *)
98 i_params : param list; (** The list of parameter descriptions. *)
99 i_raised_exceptions : raised_exception list; (** The list of raised exceptions. *)
100 i_return_value : text option; (** The description text of the return value. *)
101 i_custom : (string * text) list ; (** A text associated to a custom @-tag. *)
102 }
103
104 (** Location of elements in implementation and interface files. *)
105 type location = Odoc_types.location = {
106 loc_impl : Location.t option ; (** implementation location *)
107 loc_inter : Location.t option ; (** interface location *)
108 }
109
110 (** A dummy location. *)
111 val dummy_loc : location
112
113 (** Representation of element names. *)
114 module Name :
115 sig
116 type t = string
117
118 (** Access to the simple name. *)
119 val simple : t -> t
120
121 (** [concat t1 t2] returns the concatenation of [t1] and [t2].*)
122 val concat : t -> t -> t
123
124 (** Return the depth of the name, i.e. the number of levels to the root.
125 Example : [depth "Toto.Tutu.name"] = [3]. *)
126 val depth : t -> int
127
128 (** Take two names n1 and n2 = n3.n4 and return n4 if n3=n1 or else n2. *)
129 val get_relative : t -> t -> t
130
131 (** Take two names n1 and n2 = n3.n4 and return n4 if n3=n1 and n1<>"" or else n2. *)
132 val get_relative_opt : t -> t -> t
133
134
135 (** Return the name of the 'father' (like [dirname] for a file name).*)
136 val father : t -> t
137 end
138
139 (** Representation and manipulation of method / function / class / module parameters.*)
140 module Parameter :
141 sig
142 (** {1 Types} *)
143
144 (** Representation of a simple parameter name *)
145 type simple_name = Odoc_parameter.simple_name =
146 {
147 sn_name : string ;
148 sn_type : Types.type_expr ;
149 mutable sn_text : text option ;
150 }
151
152 (** Representation of parameter names. We need it to represent parameter names in tuples.
153 The value [Tuple ([], t)] stands for an anonymous parameter.*)
154 type param_info = Odoc_parameter.param_info =
155 Simple_name of simple_name
156 | Tuple of param_info list * Types.type_expr
157
158 (** A parameter is just a param_info.*)
159 type parameter = param_info
160
161 (** {1 Functions} *)
162
163 (** Access to the name as a string. For tuples, parentheses and commas are added. *)
164 val complete_name : parameter -> string
165
166 (** Access to the complete type. *)
167 val typ : parameter -> Types.type_expr
168
169 (** Access to the list of names ; only one for a simple parameter, or
170 a list for a tuple. *)
171 val names : parameter -> string list
172
173 (** Access to the description of a specific name.
174 @raise Not_found if no description is associated to the given name. *)
175 val desc_by_name : parameter -> string -> text option
176
177 (** Access to the type of a specific name.
178 @raise Not_found if no type is associated to the given name. *)
179 val type_by_name : parameter -> string -> Types.type_expr
180 end
181
182 (** Representation and manipulation of extensions. *)
183 module Extension :
184 sig
185 type private_flag = Odoc_extension.private_flag =
186 Private | Public
187
188 (** Used when the extension is a rebind of another extension,
189 when we have [extension Xt = Target_xt].*)
190 type extension_alias = Odoc_extension.extension_alias =
191 {
192 xa_name : Name.t ; (** The complete name of the target extension. *)
193 mutable xa_xt : t_extension_constructor option ; (** The target extension, if we found it.*)
194 }
195
196 and t_extension_constructor = Odoc_extension.t_extension_constructor =
197 {
198 xt_name : Name.t ;
199 xt_args: Odoc_type.constructor_args;
200 xt_ret: Types.type_expr option ; (** the optional return type of the extension *)
201 xt_type_extension: t_type_extension ; (** the type extension containing this constructor *)
202 xt_alias: extension_alias option ; (** [None] when the extension is not a rebind. *)
203 mutable xt_loc: Odoc_types.location ;
204 mutable xt_text: Odoc_types.info option ; (** optional user description *)
205 }
206
207 and t_type_extension = Odoc_extension.t_type_extension =
208 {
209 mutable te_info : info option ; (** Information found in the optional associated comment. *)
210 te_type_name : Name.t ; (** The type of the extension *)
211 te_type_parameters : Types.type_expr list;
212 te_private : private_flag ;
213 mutable te_constructors: t_extension_constructor list;
214 mutable te_loc : location ;
215 mutable te_code : string option ;
216 }
217
218 (** Access to the extensions in a group. *)
219 val extension_constructors : t_type_extension -> t_extension_constructor list
220
221 end
222
223 (** Representation and manipulation of exceptions. *)
224 module Exception :
225 sig
226 (** Used when the exception is a rebind of another exception,
227 when we have [exception Ex = Target_ex].*)
228 type exception_alias = Odoc_exception.exception_alias =
229 {
230 ea_name : Name.t ; (** The complete name of the target exception. *)
231 mutable ea_ex : t_exception option ; (** The target exception, if we found it.*)
232 }
233
234 and t_exception = Odoc_exception.t_exception =
235 {
236 ex_name : Name.t ;
237 mutable ex_info : info option ; (** Information found in the optional associated comment. *)
238 ex_args : Odoc_type.constructor_args;
239 ex_ret : Types.type_expr option ; (** The optional return type of the exception. *)
240 ex_alias : exception_alias option ; (** [None] when the exception is not a rebind. *)
241 mutable ex_loc : location ;
242 mutable ex_code : string option ;
243 }
244 end
245
246 (** Representation and manipulation of types.*)
247 module Type :
248 sig
249 type private_flag = Odoc_type.private_flag =
250 Private | Public
251
252 (** Description of a record type field. *)
253 type record_field = Odoc_type.record_field =
254 {
255 rf_name : string ; (** Name of the field. *)
256 rf_mutable : bool ; (** [true] if mutable. *)
257 rf_type : Types.type_expr ; (** Type of the field. *)
258 mutable rf_text : info option ; (** Optional description in the associated comment.*)
259 }
260
261 (** Description of a variant type constructor. *)
262 type constructor_args = Odoc_type.constructor_args =
263 | Cstr_record of record_field list
264 | Cstr_tuple of Types.type_expr list
265
266 type variant_constructor = Odoc_type.variant_constructor =
267 {
268 vc_name : string ; (** Name of the constructor. *)
269 vc_args : constructor_args;
270 vc_ret : Types.type_expr option ;
271 mutable vc_text : info option ; (** Optional description in the associated comment. *)
272 }
273
274 (** The various kinds of a type. *)
275 type type_kind = Odoc_type.type_kind =
276 Type_abstract (** Type is abstract, for example [type t]. *)
277 | Type_variant of variant_constructor list
278 (** constructors *)
279 | Type_record of record_field list
280 (** fields *)
281 | Type_open (** Type is open *)
282
283 type object_field = Odoc_type.object_field = {
284 of_name : string ;
285 of_type : Types.type_expr ;
286 mutable of_text : Odoc_types.info option ; (** optional user description *)
287 }
288
289 type type_manifest = Odoc_type.type_manifest =
290 | Other of Types.type_expr (** Type manifest directly taken from Typedtree. *)
291 | Object_type of object_field list
292
293 (** Representation of a type. *)
294 type t_type = Odoc_type.t_type =
295 {
296 ty_name : Name.t ; (** Complete name of the type. *)
297 mutable ty_info : info option ; (** Information found in the optional associated comment. *)
298 ty_parameters : (Types.type_expr * bool * bool) list ;
299 (** type parameters: (type, covariant, contravariant) *)
300 ty_kind : type_kind; (** Type kind. *)
301 ty_private : private_flag; (** Private or public type. *)
302 ty_manifest : type_manifest option ;
303 mutable ty_loc : location ;
304 mutable ty_code : string option;
305 }
306
307 end
308
309 (** Representation and manipulation of values, class attributes and class methods. *)
310 module Value :
311 sig
312 (** Representation of a value. *)
313 type t_value = Odoc_value.t_value =
314 {
315 val_name : Name.t ; (** Complete name of the value. *)
316 mutable val_info : info option ; (** Information found in the optional associated comment. *)
317 val_type : Types.type_expr ; (** Type of the value. *)
318 val_recursive : bool ; (** [true] if the value is recursive. *)
319 mutable val_parameters : Odoc_parameter.parameter list ; (** The parameters, if any. *)
320 mutable val_code : string option ; (** The code of the value, if we had the only the implementation file. *)
321 mutable val_loc : location ;
322 }
323
324 (** Representation of a class attribute. *)
325 type t_attribute = Odoc_value.t_attribute =
326 {
327 att_value : t_value ; (** an attribute has almost all the same information as a value *)
328 att_mutable : bool ; (** [true] if the attribute is mutable. *)
329 att_virtual : bool ; (** [true] if the attribute is virtual. *)
330 }
331
332 (** Representation of a class method. *)
333 type t_method = Odoc_value.t_method =
334 {
335 met_value : t_value ; (** a method has almost all the same information as a value *)
336 met_private : bool ; (** [true] if the method is private.*)
337 met_virtual : bool ; (** [true] if the method is virtual. *)
338 }
339
340 (** Return [true] if the value is a function, i.e. it has a functional type. *)
341 val is_function : t_value -> bool
342
343 (** Access to the description associated to the given parameter name.*)
344 val value_parameter_text_by_name : t_value -> string -> text option
345 end
346
347 (** Representation and manipulation of classes and class types.*)
348 module Class :
349 sig
350 (** {1 Types} *)
351
352 (** To keep the order of elements in a class. *)
353 type class_element = Odoc_class.class_element =
354 Class_attribute of Value.t_attribute
355 | Class_method of Value.t_method
356 | Class_comment of text
357
358 (** Used when we can reference a t_class or a t_class_type. *)
359 type cct = Odoc_class.cct =
360 Cl of t_class
361 | Cltype of t_class_type * Types.type_expr list (** Class type and type parameters. *)
362
363 and inherited_class = Odoc_class.inherited_class =
364 {
365 ic_name : Name.t ; (** Complete name of the inherited class. *)
366 mutable ic_class : cct option ; (** The associated t_class or t_class_type. *)
367 ic_text : text option ; (** The inheritance description, if any. *)
368 }
369
370 and class_apply = Odoc_class.class_apply =
371 {
372 capp_name : Name.t ; (** The complete name of the applied class. *)
373 mutable capp_class : t_class option; (** The associated t_class if we found it. *)
374 capp_params : Types.type_expr list; (** The type of expressions the class is applied to. *)
375 capp_params_code : string list ; (** The code of these expressions. *)
376 }
377
378 and class_constr = Odoc_class.class_constr =
379 {
380 cco_name : Name.t ; (** The complete name of the applied class. *)
381 mutable cco_class : cct option;
382 (** The associated class or class type if we found it. *)
383 cco_type_parameters : Types.type_expr list; (** The type parameters of the class, if needed. *)
384 }
385
386 and class_kind = Odoc_class.class_kind =
387 Class_structure of inherited_class list * class_element list
388 (** An explicit class structure, used in implementation and interface. *)
389 | Class_apply of class_apply
390 (** Application/alias of a class, used in implementation only. *)
391 | Class_constr of class_constr
392 (** A class used to give the type of the defined class,
393 instead of a structure, used in interface only.
394 For example, it will be used with the name [M1.M2....bar]
395 when the class foo is defined like this :
396 [class foo : int -> bar] *)
397 | Class_constraint of class_kind * class_type_kind
398 (** A class definition with a constraint. *)
399
400 (** Representation of a class. *)
401 and t_class = Odoc_class.t_class =
402 {
403 cl_name : Name.t ; (** Complete name of the class. *)
404 mutable cl_info : info option ; (** Information found in the optional associated comment. *)
405 cl_type : Types.class_type ; (** Type of the class. *)
406 cl_type_parameters : Types.type_expr list ; (** Type parameters. *)
407 cl_virtual : bool ; (** [true] when the class is virtual. *)
408 mutable cl_kind : class_kind ; (** The way the class is defined. *)
409 mutable cl_parameters : Parameter.parameter list ; (** The parameters of the class. *)
410 mutable cl_loc : location ;
411 }
412
413 and class_type_alias = Odoc_class.class_type_alias =
414 {
415 cta_name : Name.t ; (** Complete name of the target class type. *)
416 mutable cta_class : cct option ; (** The target t_class or t_class_type, if we found it.*)
417 cta_type_parameters : Types.type_expr list ; (** The type parameters. FIXME : use strings? *)
418 }
419
420 and class_type_kind = Odoc_class.class_type_kind =
421 Class_signature of inherited_class list * class_element list
422 | Class_type of class_type_alias (** A class type eventually applied to type args. *)
423
424 (** Representation of a class type. *)
425 and t_class_type = Odoc_class.t_class_type =
426 {
427 clt_name : Name.t ; (** Complete name of the type. *)
428 mutable clt_info : info option ; (** Information found in the optional associated comment. *)
429 clt_type : Types.class_type ;
430 clt_type_parameters : Types.type_expr list ; (** Type parameters. *)
431 clt_virtual : bool ; (** [true] if the class type is virtual *)
432 mutable clt_kind : class_type_kind ; (** The way the class type is defined. *)
433 mutable clt_loc : location ;
434 }
435
436 (** {1 Functions} *)
437
438 (** Access to the elements of a class. *)
439 val class_elements : ?trans:bool -> t_class -> class_element list
440
441 (** Access to the list of class attributes. *)
442 val class_attributes : ?trans:bool -> t_class -> Value.t_attribute list
443
444 (** Access to the description associated to the given class parameter name. *)
445 val class_parameter_text_by_name : t_class -> string -> text option
446
447 (** Access to the methods of a class. *)
448 val class_methods : ?trans:bool -> t_class -> Value.t_method list
449
450 (** Access to the comments of a class. *)
451 val class_comments : ?trans:bool -> t_class -> text list
452
453 (** Access to the elements of a class type. *)
454 val class_type_elements : ?trans:bool -> t_class_type -> class_element list
455
456 (** Access to the list of class type attributes. *)
457 val class_type_attributes : ?trans:bool -> t_class_type -> Value.t_attribute list
458
459 (** Access to the description associated to the given class type parameter name. *)
460 val class_type_parameter_text_by_name : t_class_type -> string -> text option
461
462 (** Access to the methods of a class type. *)
463 val class_type_methods : ?trans:bool -> t_class_type -> Value.t_method list
464
465 (** Access to the comments of a class type. *)
466 val class_type_comments : ?trans:bool -> t_class_type -> text list
467 end
468
469 (** Representation and manipulation of modules and module types. *)
470 module Module :
471 sig
472 (** {1 Types} *)
473
474 (** To keep the order of elements in a module. *)
475 type module_element = Odoc_module.module_element =
476 Element_module of t_module
477 | Element_module_type of t_module_type
478 | Element_included_module of included_module
479 | Element_class of Class.t_class
480 | Element_class_type of Class.t_class_type
481 | Element_value of Value.t_value
482 | Element_type_extension of Extension.t_type_extension
483 | Element_exception of Exception.t_exception
484 | Element_type of Type.t_type
485 | Element_module_comment of text
486
487 (** Used where we can reference t_module or t_module_type. *)
488 and mmt = Odoc_module.mmt =
489 | Mod of t_module
490 | Modtype of t_module_type
491
492 and included_module = Odoc_module.included_module =
493 {
494 im_name : Name.t ; (** Complete name of the included module. *)
495 mutable im_module : mmt option ; (** The included module or module type, if we found it. *)
496 mutable im_info : Odoc_types.info option ; (** comment associated with the include directive *)
497 }
498
499 and module_alias = Odoc_module.module_alias =
500 {
501 ma_name : Name.t ; (** Complete name of the target module. *)
502 mutable ma_module : mmt option ; (** The real module or module type if we could associate it. *)
503 }
504
505 and module_parameter = Odoc_module.module_parameter = {
506 mp_name : string ; (** the name *)
507 mp_type : Types.module_type option ; (** the type *)
508 mp_type_code : string ; (** the original code *)
509 mp_kind : module_type_kind ; (** the way the parameter was built *)
510 }
511
512 (** Different kinds of a module. *)
513 and module_kind = Odoc_module.module_kind =
514 | Module_struct of module_element list (** A complete module structure. *)
515 | Module_alias of module_alias (** Complete name and corresponding module if we found it *)
516 | Module_functor of module_parameter * module_kind
517 (** A functor, with its parameter and the rest of its definition *)
518 | Module_apply of module_kind * module_kind
519 (** A module defined by application of a functor. *)
520 | Module_with of module_type_kind * string
521 (** A module whose type is a with ... constraint.
522 Should appear in interface files only. *)
523 | Module_constraint of module_kind * module_type_kind
524 (** A module constraint by a module type. *)
525 | Module_typeof of string (** by now only the code of the module expression *)
526 | Module_unpack of string * module_type_alias (** code of the expression and module type alias *)
527
528 (** Representation of a module. *)
529 and t_module = Odoc_module.t_module =
530 {
531 m_name : Name.t ; (** Complete name of the module. *)
532 mutable m_type : Types.module_type ; (** The type of the module. *)
533 mutable m_info : info option ; (** Information found in the optional associated comment. *)
534 m_is_interface : bool ; (** [true] for modules read from interface files *)
535 m_file : string ; (** The file the module is defined in. *)
536 mutable m_kind : module_kind ; (** The way the module is defined. *)
537 mutable m_loc : location ;
538 mutable m_top_deps : Name.t list ; (** The toplevels module names this module depends on. *)
539 mutable m_code : string option ; (** The whole code of the module *)
540 mutable m_code_intf : string option ; (** The whole code of the interface of the module *)
541 m_text_only : bool ; (** [true] if the module comes from a text file *)
542 }
543
544 and module_type_alias = Odoc_module.module_type_alias =
545 {
546 mta_name : Name.t ; (** Complete name of the target module type. *)
547 mutable mta_module : t_module_type option ; (** The real module type if we could associate it. *)
548 }
549
550 (** Different kinds of module type. *)
551 and module_type_kind = Odoc_module.module_type_kind =
552 | Module_type_struct of module_element list (** A complete module signature. *)
553 | Module_type_functor of module_parameter * module_type_kind
554 (** A functor, with its parameter and the rest of its definition *)
555 | Module_type_alias of module_type_alias
556 (** Complete alias name and corresponding module type if we found it. *)
557 | Module_type_with of module_type_kind * string
558 (** The module type kind and the code of the with constraint. *)
559 | Module_type_typeof of string
560 (** by now only the code of the module expression *)
561
562 (** Representation of a module type. *)
563 and t_module_type = Odoc_module.t_module_type =
564 {
565 mt_name : Name.t ; (** Complete name of the module type. *)
566 mutable mt_info : info option ; (** Information found in the optional associated comment. *)
567 mutable mt_type : Types.module_type option ; (** [None] means that the module type is abstract. *)
568 mt_is_interface : bool ; (** [true] for modules read from interface files. *)
569 mt_file : string ; (** The file the module type is defined in. *)
570 mutable mt_kind : module_type_kind option ;
571 (** The way the module is defined. [None] means that module type is abstract.
572 It is always [None] when the module type was extracted from the implementation file.
573 That means module types are only analysed in interface files. *)
574 mutable mt_loc : location ;
575 }
576
577 (** {1 Functions for modules} *)
578
579 (** Access to the elements of a module. *)
580 val module_elements : ?trans:bool -> t_module -> module_element list
581
582 (** Access to the submodules of a module. *)
583 val module_modules : ?trans:bool -> t_module -> t_module list
584
585 (** Access to the module types of a module. *)
586 val module_module_types : ?trans:bool -> t_module -> t_module_type list
587
588 (** Access to the included modules of a module. *)
589 val module_included_modules : ?trans:bool-> t_module -> included_module list
590
591 (** Access to the type extensions of a module. *)
592 val module_type_extensions : ?trans:bool-> t_module -> Extension.t_type_extension list
593
594 (** Access to the exceptions of a module. *)
595 val module_exceptions : ?trans:bool-> t_module -> Exception.t_exception list
596
597 (** Access to the types of a module. *)
598 val module_types : ?trans:bool-> t_module -> Type.t_type list
599
600 (** Access to the values of a module. *)
601 val module_values : ?trans:bool -> t_module -> Value.t_value list
602
603 (** Access to functional values of a module. *)
604 val module_functions : ?trans:bool-> t_module -> Value.t_value list
605
606 (** Access to non-functional values of a module. *)
607 val module_simple_values : ?trans:bool-> t_module -> Value.t_value list
608
609 (** Access to the classes of a module. *)
610 val module_classes : ?trans:bool-> t_module -> Class.t_class list
611
612 (** Access to the class types of a module. *)
613 val module_class_types : ?trans:bool-> t_module -> Class.t_class_type list
614
615 (** The list of classes defined in this module and all its submodules and functors. *)
616 val module_all_classes : ?trans:bool-> t_module -> Class.t_class list
617
618 (** [true] if the module is functor. *)
619 val module_is_functor : t_module -> bool
620
621 (** The list of couples (module parameter, optional description). *)
622 val module_parameters : ?trans:bool-> t_module -> (module_parameter * text option) list
623
624 (** The list of module comments. *)
625 val module_comments : ?trans:bool-> t_module -> text list
626
627 (** {1 Functions for module types} *)
628
629 (** Access to the elements of a module type. *)
630 val module_type_elements : ?trans:bool-> t_module_type -> module_element list
631
632 (** Access to the submodules of a module type. *)
633 val module_type_modules : ?trans:bool-> t_module_type -> t_module list
634
635 (** Access to the module types of a module type. *)
636 val module_type_module_types : ?trans:bool-> t_module_type -> t_module_type list
637
638 (** Access to the included modules of a module type. *)
639 val module_type_included_modules : ?trans:bool-> t_module_type -> included_module list
640
641 (** Access to the exceptions of a module type. *)
642 val module_type_exceptions : ?trans:bool-> t_module_type -> Exception.t_exception list
643
644 (** Access to the types of a module type. *)
645 val module_type_types : ?trans:bool-> t_module_type -> Type.t_type list
646
647 (** Access to the values of a module type. *)
648 val module_type_values : ?trans:bool-> t_module_type -> Value.t_value list
649
650 (** Access to functional values of a module type. *)
651 val module_type_functions : ?trans:bool-> t_module_type -> Value.t_value list
652
653 (** Access to non-functional values of a module type. *)
654 val module_type_simple_values : ?trans:bool-> t_module_type -> Value.t_value list
655
656 (** Access to the classes of a module type. *)
657 val module_type_classes : ?trans:bool-> t_module_type -> Class.t_class list
658
659 (** Access to the class types of a module type. *)
660 val module_type_class_types : ?trans:bool-> t_module_type -> Class.t_class_type list
661
662 (** The list of classes defined in this module type and all its submodules and functors. *)
663 val module_type_all_classes : ?trans:bool-> t_module_type -> Class.t_class list
664
665 (** [true] if the module type is functor. *)
666 val module_type_is_functor : t_module_type -> bool
667
668 (** The list of couples (module parameter, optional description). *)
669 val module_type_parameters : ?trans:bool-> t_module_type -> (module_parameter * text option) list
670
671 (** The list of module comments. *)
672 val module_type_comments : ?trans:bool-> t_module_type -> text list
673 end
674
675
676 (** {2 Getting strings from values} *)
677
678 (** This function is used to reset the names of type variables.
679 It must be called when printing the whole type of a function,
680 but not when printing the type of its parameters. Same for
681 classes (call it) and methods and attributes (don't call it).*)
682 val reset_type_names : unit -> unit
683
684 (** [string_of_variance t (covariant, invariant)] returns ["+"] if
685 the given information means "covariant", ["-"] if it means
686 "contravariant", orelse [""], and always [""] if the given
687 type is not an abstract type with no manifest (i.e. no need
688 for the variance to be printed).*)
689 val string_of_variance : Type.t_type -> (bool * bool) -> string
690
691 (** This function returns a string representing a Types.type_expr. *)
692 val string_of_type_expr : Types.type_expr -> string
693
694 (** @return a string to display the parameters of the given class,
695 in the same form as the compiler. *)
696 val string_of_class_params : Class.t_class -> string
697
698 (** This function returns a string to represent the given list of types,
699 with a given separator. *)
700 val string_of_type_list : ?par: bool -> string -> Types.type_expr list -> string
701
702 (** This function returns a string to represent the list of type parameters
703 for the given type. *)
704 val string_of_type_param_list : Type.t_type -> string
705
706 (** This function returns a string to represent the list of type parameters
707 for the given type extension. *)
708 val string_of_type_extension_param_list : Extension.t_type_extension -> string
709
710 (** This function returns a string to represent the given list of
711 type parameters of a class or class type,
712 with a given separator. *)
713 val string_of_class_type_param_list : Types.type_expr list -> string
714
715 (** This function returns a string representing a [Types.module_type].
716 @param complete indicates if we must print complete signatures
717 or just [sig end]. Default is [false].
718 @param code if [complete = false] and the type contains something else
719 than identificators and functors, then the given code is used.
720 *)
721 val string_of_module_type : ?code: string -> ?complete: bool -> Types.module_type -> string
722
723 (** This function returns a string representing a [Types.class_type].
724 @param complete indicates if we must print complete signatures
725 or just [object end]. Default is [false].
726 *)
727 val string_of_class_type : ?complete: bool -> Types.class_type -> string
728
729
730 (** Get a string from a text. *)
731 val string_of_text : text -> string
732
733 (** Get a string from an info structure. *)
734 val string_of_info : info -> string
735
736 (** @return a string to describe the given type. *)
737 val string_of_type : Type.t_type -> string
738
739 val string_of_record : Type.record_field list -> string
740
741 (** @return a string to describe the given type extension. *)
742 val string_of_type_extension : Extension.t_type_extension -> string
743
744 (** @return a string to describe the given exception. *)
745 val string_of_exception : Exception.t_exception -> string
746
747 (** @return a string to describe the given value. *)
748 val string_of_value : Value.t_value -> string
749
750 (** @return a string to describe the given attribute. *)
751 val string_of_attribute : Value.t_attribute -> string
752
753 (** @return a string to describe the given method. *)
754 val string_of_method : Value.t_method -> string
755
756 (** {2 Miscellaneous functions} *)
757
758 (** Return the first sentence (until the first dot followed by a blank
759 or the first blank line) of a text.
760 Don't stop in the middle of [Code], [CodePre], [Verbatim], [List], [Enum],
761 [Latex], [Link], [Ref], [Subscript] or [Superscript]. *)
762 val first_sentence_of_text : text -> text
763
764 (** Return the first sentence (until the first dot followed by a blank
765 or the first blank line) of a text, and the remaining text after.
766 Don't stop in the middle of [Code], [CodePre], [Verbatim], [List], [Enum],
767 [Latex], [Link], [Ref], [Subscript] or [Superscript].*)
768 val first_sentence_and_rest_of_text : text -> text * text
769
770 (** Return the given [text] without any title or list. *)
771 val text_no_title_no_list : text -> text
772
773 (** [concat sep l] concats the given list of text [l], each separated with
774 the text [sep]. *)
775 val text_concat : Odoc_types.text -> Odoc_types.text list -> Odoc_types.text
776
777 (** Return the list of titles in a [text].
778 A title is a title level, an optional label and a text.*)
779 val get_titles_in_text : text -> (int * string option * text) list
780
781 (** Take a sorted list of elements, a function to get the name
782 of an element and return the list of list of elements,
783 where each list group elements beginning by the same letter.
784 Since the original list is sorted, elements whose name does not
785 begin with a letter should be in the first returned list.*)
786 val create_index_lists : 'a list -> ('a -> string) -> 'a list list
787
788 (** Take a type and remove the option top constructor. This is
789 useful when printing labels, we then remove the top option constructor
790 for optional labels.*)
791 val remove_option : Types.type_expr -> Types.type_expr
792
793 (** Return [true] if the given label is optional.*)
794 val is_optional : Asttypes.arg_label -> bool
795
796 (** Return the label name for the given label,
797 i.e. removes the beginning '?' if present.*)
798 val label_name : Asttypes.arg_label -> string
799
800 (** Return the given name where the module name or
801 part of it was removed, according to the list of modules
802 which must be hidden (cf {!Odoc_args.hidden_modules})*)
803 val use_hidden_modules : Name.t -> Name.t
804
805 (** Print the given string if the verbose mode is activated. *)
806 val verbose : string -> unit
807
808 (** Print a warning message to stderr.
809 If warnings must be treated as errors, then the
810 error counter is incremented. *)
811 val warning : string -> unit
812
813 (** A flag to indicate whether ocamldoc warnings must be printed or not. *)
814 val print_warnings : bool ref
815
816 (** Increment this counter when an error is encountered.
817 The ocamldoc tool will print the number of errors
818 encountered exit with code 1 if this number is greater
819 than 0. *)
820 val errors : int ref
821
822 (** Apply a function to an optional value. *)
823 val apply_opt : ('a -> 'b) -> 'a option -> 'b option
824
825 (** Apply a function to a first value if it is
826 not different from a second value. If the two values
827 are different, return the second one.*)
828 val apply_if_equal : ('a -> 'a) -> 'a -> 'a -> 'a
829
830 (** [text_of_string s] returns the text structure from the
831 given string.
832 @raise Text_syntax if a syntax error is encountered. *)
833 val text_of_string : string -> text
834
835 (** [text_string_of_text text] returns the string representing
836 the given [text]. This string can then be parsed again
837 by {!Odoc_info.text_of_string}.*)
838 val text_string_of_text : text -> string
839
840 (** [info_of_string s] parses the given string
841 like a regular ocamldoc comment and return an
842 {!Odoc_info.info} structure.
843 @return an empty structure if there was a syntax error. TODO: change this
844 *)
845 val info_of_string : string -> info
846
847 (** [info_string_of_info info] returns the string representing
848 the given [info]. This string can then be parsed again
849 by {!Odoc_info.info_of_string}.*)
850 val info_string_of_info : info -> string
851
852 (** [info_of_comment_file file] parses the given file
853 and return an {!Odoc_info.info} structure. The content of the
854 file must have the same syntax as the content of a special comment.
855 The given module list is used for cross reference.
856 @raise Failure if the file could not be opened or there is a
857 syntax error.
858 *)
859 val info_of_comment_file : Module.t_module list -> string -> info
860
861 (** [remove_ending_newline s] returns [s] without the optional ending newline. *)
862 val remove_ending_newline : string -> string
863
864 (** Research in elements *)
865 module Search :
866 sig
867 type result_element = Odoc_search.result_element =
868 Res_module of Module.t_module
869 | Res_module_type of Module.t_module_type
870 | Res_class of Class.t_class
871 | Res_class_type of Class.t_class_type
872 | Res_value of Value.t_value
873 | Res_type of Type.t_type
874 | Res_extension of Extension.t_extension_constructor
875 | Res_exception of Exception.t_exception
876 | Res_attribute of Value.t_attribute
877 | Res_method of Value.t_method
878 | Res_section of string * text
879 | Res_recfield of Type.t_type * Type.record_field
880 | Res_const of Type.t_type * Type.variant_constructor
881
882 (** The type representing a research result.*)
883 type search_result = result_element list
884
885 (** Research of the elements whose name matches the given regular expression.*)
886 val search_by_name : Module.t_module list -> Str.regexp -> search_result
887
888 (** A function to search all the values in a list of modules. *)
889 val values : Module.t_module list -> Value.t_value list
890
891 (** A function to search all the extensions in a list of modules. *)
892 val extensions : Module.t_module list -> Extension.t_extension_constructor list
893
894 (** A function to search all the exceptions in a list of modules. *)
895 val exceptions : Module.t_module list -> Exception.t_exception list
896
897 (** A function to search all the types in a list of modules. *)
898 val types : Module.t_module list -> Type.t_type list
899
900 (** A function to search all the class attributes in a list of modules. *)
901 val attributes : Module.t_module list -> Value.t_attribute list
902
903 (** A function to search all the class methods in a list of modules. *)
904 val methods : Module.t_module list -> Value.t_method list
905
906 (** A function to search all the classes in a list of modules. *)
907 val classes : Module.t_module list -> Class.t_class list
908
909 (** A function to search all the class types in a list of modules. *)
910 val class_types : Module.t_module list -> Class.t_class_type list
911
912 (** A function to search all the modules in a list of modules. *)
913 val modules : Module.t_module list -> Module.t_module list
914
915 (** A function to search all the module types in a list of modules. *)
916 val module_types : Module.t_module list -> Module.t_module_type list
917
918 end
919
920 (** Scanning of collected information *)
921 module Scan :
922 sig
923 class scanner :
924 object
925
926 method scan_value : Value.t_value -> unit
927
928 method scan_type_pre : Type.t_type -> bool
929 method scan_type_const : Type.t_type -> Type.variant_constructor -> unit
930 method scan_type_recfield : Type.t_type -> Type.record_field -> unit
931 method scan_type : Type.t_type -> unit
932 method scan_extension_constructor : Extension.t_extension_constructor -> unit
933 method scan_exception : Exception.t_exception -> unit
934 method scan_attribute : Value.t_attribute -> unit
935 method scan_method : Value.t_method -> unit
936 method scan_included_module : Module.included_module -> unit
937
938 (** Scan of a type extension *)
939
940 (** Override this method to perform controls on the extension's type,
941 private and info. This method is called before scanning the
942 extension's constructors.
943 @return true if the extension's constructors must be scanned.*)
944 method scan_type_extension_pre : Extension.t_type_extension -> bool
945
946 (** This method scans the constructors of the given type extension. *)
947 method scan_type_extension_constructors : Extension.t_type_extension -> unit
948
949 (** Scan of a type extension. Should not be overridden. It calls [scan_type_extension_pre]
950 and if [scan_type_extension_pre] returns [true], then it calls scan_type_extension_constructors.*)
951 method scan_type_extension : Extension.t_type_extension -> unit
952
953 (** Scan of a class. *)
954
955 (** Scan of a comment inside a class. *)
956 method scan_class_comment : text -> unit
957
958 (** Override this method to perform controls on the class comment
959 and params. This method is called before scanning the class elements.
960 @return true if the class elements must be scanned.*)
961 method scan_class_pre : Class.t_class -> bool
962
963 (** This method scans the elements of the given class. *)
964 method scan_class_elements : Class.t_class -> unit
965
966 (** Scan of a class. Should not be overridden. It calls [scan_class_pre]
967 and if [scan_class_pre] returns [true], then it calls scan_class_elements.*)
968 method scan_class : Class.t_class -> unit
969
970 (** Scan of a class type. *)
971
972 (** Scan of a comment inside a class type. *)
973 method scan_class_type_comment : text -> unit
974
975 (** Override this method to perform controls on the class type comment
976 and form. This method is called before scanning the class type elements.
977 @return true if the class type elements must be scanned.*)
978 method scan_class_type_pre : Class.t_class_type -> bool
979
980 (** This method scans the elements of the given class type. *)
981 method scan_class_type_elements : Class.t_class_type -> unit
982
983 (** Scan of a class type. Should not be overridden. It calls [scan_class_type_pre]
984 and if [scan_class_type_pre] returns [true], then it calls scan_class_type_elements.*)
985 method scan_class_type : Class.t_class_type -> unit
986
987 (** Scan of modules. *)
988
989 (** Scan of a comment inside a module. *)
990 method scan_module_comment : text -> unit
991
992 (** Override this method to perform controls on the module comment
993 and form. This method is called before scanning the module elements.
994 @return true if the module elements must be scanned.*)
995 method scan_module_pre : Module.t_module -> bool
996
997 (** This method scans the elements of the given module. *)
998 method scan_module_elements : Module.t_module -> unit
999
1000 (** Scan of a module. Should not be overridden. It calls [scan_module_pre]
1001 and if [scan_module_pre] returns [true], then it calls scan_module_elements.*)
1002 method scan_module : Module.t_module -> unit
1003
1004 (** Scan of module types. *)
1005
1006 (** Scan of a comment inside a module type. *)
1007 method scan_module_type_comment : text -> unit
1008
1009 (** Override this method to perform controls on the module type comment
1010 and form. This method is called before scanning the module type elements.
1011 @return true if the module type elements must be scanned. *)
1012 method scan_module_type_pre : Module.t_module_type -> bool
1013
1014 (** This method scans the elements of the given module type. *)
1015 method scan_module_type_elements : Module.t_module_type -> unit
1016
1017 (** Scan of a module type. Should not be overridden. It calls [scan_module_type_pre]
1018 and if [scan_module_type_pre] returns [true], then it calls scan_module_type_elements.*)
1019 method scan_module_type : Module.t_module_type -> unit
1020
1021 (** Main scanning method. *)
1022
1023 (** Scan a list of modules. *)
1024 method scan_module_list : Module.t_module list -> unit
1025 end
1026 end
1027
1028 (** Computation of dependencies. *)
1029 module Dep :
1030 sig
1031 (** Modify the module dependencies of the given list of modules,
1032 to get the minimum transitivity kernel. *)
1033 val kernel_deps_of_modules : Module.t_module list -> unit
1034
1035 (** Return the list of dependencies between the given types,
1036 in the form of a list [(type name, names of types it depends on)].
1037 @param kernel indicates if we must keep only the transitivity kernel
1038 of the dependencies. Default is [false].
1039 *)
1040 val deps_of_types : ?kernel: bool -> Type.t_type list -> (Type.t_type * (Name.t list)) list
1041 end
1042
1043 (** {1 Some global variables} *)
1044
1045 module Global :
1046 sig
1047 val errors : int ref
1048 val warn_error : bool ref
1049
1050 (** The file used by the generators outputting only one file. *)
1051 val out_file : string ref
1052
1053 (** Verbose mode or not. *)
1054 val verbose : bool ref
1055
1056 (** The directory where files have to be generated. *)
1057 val target_dir : string ref
1058
1059 (** The optional title to use in the generated documentation. *)
1060 val title : string option ref
1061
1062 (** The optional file whose content can be used as intro text. *)
1063 val intro_file : string option ref
1064
1065 (** The flag which indicates if we must generate a table of contents. *)
1066 val with_toc : bool ref
1067
1068 (** The flag which indicates if we must generate an index. *)
1069 val with_index : bool ref
1070
1071 (** The flag which indicates if we must generate a header.*)
1072 val with_header : bool ref
1073
1074 (** The flag which indicates if we must generate a trailer.*)
1075 val with_trailer : bool ref
1076 end
1077
1078 (** Analysis of the given source files.
1079 @param init is the list of modules already known from a previous analysis.
1080 @return the list of analysed top modules. *)
1081 val analyse_files :
1082 ?merge_options:Odoc_types.merge_option list ->
1083 ?include_dirs:string list ->
1084 ?labels:bool ->
1085 ?sort_modules:bool ->
1086 ?no_stop:bool ->
1087 ?init: Odoc_module.t_module list ->
1088 Odoc_global.source_file list ->
1089 Module.t_module list
1090
1091 (** Dump of a list of modules into a file.
1092 @raise Failure if an error occurs.*)
1093 val dump_modules : string -> Odoc_module.t_module list -> unit
1094
1095 (** Load of a list of modules from a file.
1096 @raise Failure if an error occurs.*)
1097 val load_modules : string -> Odoc_module.t_module list
1098