Odoc_info (p.ocaml-compiler.5.3.0.doc.odoc_info.Odoc

type ref_kind = Odoc_types.ref_kind =

| RK_module
| RK_module_type
| RK_class
| RK_class_type
| RK_value
| RK_type
| RK_extension
| RK_exception
| RK_attribute
| RK_method
| RK_section of text
| RK_recfield
| RK_const

The different kinds of element references.

and text_element = Odoc_types.text_element =

| Raw of string
(*
Raw text.
*)
| Code of string
(*
The string is source code.
*)
| CodePre of string
(*
The string is pre-formatted source code.
*)
| Verbatim of string
(*
String 'as is'.
*)
| Bold of text
(*
Text in bold style.
*)
| Italic of text
(*
Text in italic.
*)
| Emphasize of text
(*
Emphasized text.
*)
| Center of text
(*
Centered text.
*)
| Left of text
(*
Left alignment.
*)
| Right of text
(*
Right alignment.
*)
| List of text list
(*
A list.
*)
| Enum of text list
(*
An enumerated list.
*)
| Newline
(*
To force a line break.
*)
| Block of text
(*
Like html's block quote.
*)
| Title of int * string option * text
(*
Style number, optional label, and text.
*)
| Latex of string
(*
A string for latex.
*)
| Link of string * text
(*
A reference string and the link text.
*)
| Ref of string * ref_kind option * text option
(*
A reference to an element. Complete name and kind. An optional text can be given to display this text instead of the element name.
*)
| Superscript of text
(*
Superscripts.
*)
| Subscript of text
(*
Subscripts.
*)
| Module_list of string list
(*
The table of the given modules with their abstract.
*)
| Index_list
(*
The links to the various indexes (values, types, ...)
*)
| Custom of string * text
(*
to extend {foo syntax
*)
| Target of string * string
(*
(target, code) : to specify code specific to a target format
*)

and text = text_element list

A text is a list of text_element. The order matters.

type see_ref = Odoc_types.see_ref =

| See_url of string
| See_file of string
| See_doc of string

The different forms of references in @see tags.

exception Text_syntax of int * int * string

Raised when parsing string to build a Odoc_info.text structure. (line, char, string)

type see = see_ref * text

The information in a @see tag.

type param = string * text

Parameter name and description.

type raised_exception = string * text

Raised exception name and description.

type alert = Odoc_types.alert = {

alert_name : string;
alert_payload : string option;

}

type info = Odoc_types.info = {

i_desc : text option;
(*
The description text.
*)
i_authors : string list;
(*
The list of authors in @author tags.
*)
i_version : string option;
(*
The string in the @version tag.
*)
i_sees : see list;
(*
The list of @see tags.
*)
i_since : string option;
(*
The string in the @since tag.
*)
i_before : (string * text) list;
(*
the version number and text in @before tag
*)
i_deprecated : text option;
(*
The description text of the @deprecated tag.
*)
i_params : param list;
(*
The list of parameter descriptions.
*)
i_raised_exceptions : raised_exception list;
(*
The list of raised exceptions.
*)
i_return_value : text option;
(*
The description text of the return value.
*)
i_custom : (string * text) list;
(*
A text associated to a custom @-tag.
*)
i_alerts : alert list;
(*
Alerts associated to the same item. Not from special comments.
*)

}

Information in a special comment

before 3.12
@before information was not present.

type location = Odoc_types.location = {

loc_impl : Location.t option;
(*
implementation location
*)
loc_inter : Location.t option;
(*
interface location
*)

}

Location of elements in implementation and interface files.

val dummy_loc : location

A dummy location.

module Name : sig ... end

Representation of element names.

module Parameter : sig ... end

Representation and manipulation of method / function / class / module parameters.

module Extension : sig ... end

Representation and manipulation of extensions.

module Exception : sig ... end

Representation and manipulation of exceptions.

module Type : sig ... end

Representation and manipulation of types.

module Value : sig ... end

Representation and manipulation of values, class attributes and class methods.

module Class : sig ... end

Representation and manipulation of classes and class types.

module Module : sig ... end

Representation and manipulation of modules and module types.

Getting strings from values

val reset_type_names : unit -> unit

This function is used to reset the names of type variables. It must be called when printing the whole type of a function, but not when printing the type of its parameters. Same for classes (call it) and methods and attributes (don't call it).

val string_of_variance : Type.t_type -> Types.Variance.t -> string

string_of_variance t variance returns the variance and injectivity annotation (e.g "+" for covariance, "-" for contravariance, "!-" for injectivity) if the type t is abstract.

val string_of_type_expr : Types.type_expr -> string

This function returns a string representing a Types.type_expr.

val string_of_class_params : Class.t_class -> string

returns
a string to display the parameters of the given class, in the same form as the compiler.

val string_of_type_list : ?par:bool -> string -> Types.type_expr list -> string

This function returns a string to represent the given list of types, with a given separator.

val string_of_type_param_list : Type.t_type -> string

This function returns a string to represent the list of type parameters for the given type.

val string_of_type_extension_param_list : Extension.t_type_extension -> string

This function returns a string to represent the list of type parameters for the given type extension.

val string_of_class_type_param_list : Types.type_expr list -> string

This function returns a string to represent the given list of type parameters of a class or class type, with a given separator.

val string_of_module_type : 
  ?code:string ->
  ?complete:bool ->
  Types.module_type ->
  string

This function returns a string representing a Types.module_type.

parameter complete
indicates if we must print complete signatures or just sig end. Default is false.

parameter code
if complete = false and the type contains something else than identificators and functors, then the given code is used.

val string_of_class_type : ?complete:bool -> Types.class_type -> string

This function returns a string representing a Types.class_type.

parameter complete
indicates if we must print complete signatures or just object end. Default is false.

val string_of_text : text -> string

Get a string from a text.

val string_of_info : info -> string

Get a string from an info structure.

val string_of_type : Type.t_type -> string

returns
a string to describe the given type.

val string_of_record : Type.record_field list -> string

val string_of_type_extension : Extension.t_type_extension -> string

returns
a string to describe the given type extension.

val string_of_exception : Exception.t_exception -> string

returns
a string to describe the given exception.

val string_of_value : Value.t_value -> string

returns
a string to describe the given value.

val string_of_attribute : Value.t_attribute -> string

returns
a string to describe the given attribute.

val string_of_method : Value.t_method -> string

returns
a string to describe the given method.

Miscellaneous functions

val first_sentence_of_text : text -> text

Return the first sentence (until the first dot followed by a blank or the first blank line) of a text. Don't stop in the middle of Code, CodePre, Verbatim, List, Enum, Latex, Link, Ref, Subscript or Superscript.

val first_sentence_and_rest_of_text : text -> text * text

Return the first sentence (until the first dot followed by a blank or the first blank line) of a text, and the remaining text after. Don't stop in the middle of Code, CodePre, Verbatim, List, Enum, Latex, Link, Ref, Subscript or Superscript.

val text_no_title_no_list : text -> text

Return the given text without any title or list.

val text_concat : Odoc_types.text -> Odoc_types.text list -> Odoc_types.text

concat sep l concats the given list of text l, each separated with the text sep.

val get_titles_in_text : text -> (int * string option * text) list

Return the list of titles in a text. A title is a title level, an optional label and a text.

val create_index_lists : 'a list -> ('a -> string) -> 'a list list

Take a sorted list of elements, a function to get the name of an element and return the list of list of elements, where each list group elements beginning by the same letter. Since the original list is sorted, elements whose name does not begin with a letter should be in the first returned list.

val remove_option : Types.type_expr -> Types.type_expr

Take a type and remove the option top constructor. This is useful when printing labels, we then remove the top option constructor for optional labels.

val is_optional : Asttypes.arg_label -> bool

Return true if the given label is optional.

val label_name : Asttypes.arg_label -> string

Return the label name for the given label, i.e. removes the beginning '?' if present.

val use_hidden_modules : Name.t -> Name.t

Return the given name where the module name or part of it was removed, according to the list of modules which must be hidden (cf Odoc_args.hidden_modules)

val verbose : string -> unit

Print the given string if the verbose mode is activated.

val warning : string -> unit

Print a warning message to stderr. If warnings must be treated as errors, then the error counter is incremented.

val print_warnings : bool ref

A flag to indicate whether ocamldoc warnings must be printed or not.

val errors : int ref

Increment this counter when an error is encountered. The ocamldoc tool will print the number of errors encountered exit with code 1 if this number is greater than 0.

val apply_opt : ('a -> 'b) -> 'a option -> 'b option

Apply a function to an optional value.

val apply_if_equal : ('a -> 'a) -> 'a -> 'a -> 'a

Apply a function to a first value if it is not different from a second value. If the two values are different, return the second one.

val text_of_string : string -> text

text_of_string s returns the text structure from the given string.

raises Text_syntax
if a syntax error is encountered.

val text_string_of_text : text -> string

text_string_of_text text returns the string representing the given text. This string can then be parsed again by Odoc_info.text_of_string.

val info_of_string : string -> info

info_of_string s parses the given string like a regular ocamldoc comment and return an Odoc_info.info structure.

returns
an empty structure if there was a syntax error. TODO: change this

val info_of_comment_file : Module.t_module list -> string -> info

info_of_comment_file file parses the given file and return an Odoc_info.info structure. The content of the file must have the same syntax as the content of a special comment. The given module list is used for cross reference.

raises Failure
if the file could not be opened or there is a syntax error.

val remove_ending_newline : string -> string

remove_ending_newline s returns s without the optional ending newline.

module Search : sig ... end

Research in elements

module Scan : sig ... end

Scanning of collected information

module Dep : sig ... end

Computation of dependencies.

Some global variables

module Global : sig ... end

val analyse_files : 
  ?merge_options:Odoc_types.merge_option list ->
  ?include_dirs:string list ->
  ?hidden_include_dirs:string list ->
  ?labels:bool ->
  ?sort_modules:bool ->
  ?no_stop:bool ->
  ?init:Odoc_module.t_module list ->
  Odoc_global.source_file list ->
  Module.t_module list

Analysis of the given source files.

parameter init
is the list of modules already known from a previous analysis.

returns
the list of analysed top modules.

val dump_modules : string -> Odoc_module.t_module list -> unit

Dump of a list of modules into a file.

raises Failure
if an error occurs.

val load_modules : string -> Odoc_module.t_module list

Load of a list of modules from a file.

raises Failure
if an error occurs.