ocamldoc/odoc_comments.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 (** Analysis of comments. *)
  15
  16 val simple_blank : string
  17
  18 (** The type of modules in argument to Info_retriever *)
  19 module type Texter =
  20   sig
  21     (** Return a text structure from a string. *)
  22     val text_of_string : string -> Odoc_types.text
  23   end
  24
  25 (** The basic module for special comments analysis.*)
  26 module Basic_info_retriever :
  27   sig
  28     (** Return true if the given string contains a blank line. *)
  29     val blank_line_outside_simple :
  30         string -> string -> bool
  31
  32     (** This function retrieves all the special comments in the given string. *)
  33     val all_special : string -> string -> int * Odoc_types.info list
  34
  35     (** [just_after_special file str] return the pair ([length], [info_opt])
  36        where [info_opt] is the first optional special comment found
  37        in [str], without any blank line before. [length] is the number
  38        of chars from the beginning of [str] to the end of the special comment. *)
  39     val just_after_special :
  40         string -> string -> int * Odoc_types.info option
  41
  42     (** [first_special file str] return the pair ([length], [info_opt])
  43        where [info_opt] is the first optional special comment found
  44        in [str]. [length] is the number of chars from the beginning of
  45        [str] to the end of the special comment. *)
  46     val first_special :
  47         string -> string -> int * Odoc_types.info option
  48
  49     (** Return a pair [(comment_opt, element_comment_list)], where [comment_opt] is the last special
  50        comment found in the given string and not followed by a blank line,
  51        and [element_comment_list] the list of values built from the other
  52        special comments found and the given function. *)
  53     val get_comments :
  54         (Odoc_types.text -> 'a) ->
  55           string -> string -> Odoc_types.info option * 'a list
  56
  57   end
  58
  59 (** [info_of_string s] parses the given string
  60    like a regular ocamldoc comment and return an
  61    {!Odoc_types.info} structure.
  62    @return an empty structure if there was a syntax error. TODO: change this
  63 *)
  64 val info_of_string : string -> Odoc_types.info
  65
  66 (** [info_of_comment_file file] parses the given file
  67    and return an {!Odoc_types.info} structure. The content of the
  68    file must have the same syntax as the content of a special comment.
  69    The given module list is used for cross reference.
  70    @raise Failure is the file could not be opened or there is a
  71    syntax error.
  72 *)
  73 val info_of_comment_file :
  74     Odoc_module.t_module list -> string -> Odoc_types.info