ocamldoc/odoc_info.mli

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