PR#6257: allow full doc comments on variant constructors and record fields

git-svn-id: http://caml.inria.fr/svn/ocaml/trunk@14343 f963ae5c-01c2-4b8c-9fe0-0dff7051ff02

10 files changed, 152 insertions, 132 deletions

diff --git a/ocamldoc/odoc_cross.ml b/ocamldoc/odoc_cross.ml
index fcd60dc3bf..70c3c0eb26 100644
--- a/ocamldoc/odoc_cross.ml
+++ b/ocamldoc/odoc_cross.ml
@@ -950,11 +950,11 @@ and assoc_comments_type module_list t =
     Type_abstract -> ()
   | Type_variant vl ->
       List.iter
-        (fun vc -> vc.vc_text <- ao (assoc_comments_text parent module_list) vc.vc_text)
+        (fun vc -> vc.vc_text <- ao (assoc_comments_info parent module_list) vc.vc_text)
         vl
   | Type_record fl ->
       List.iter
-        (fun rf -> rf.rf_text <- ao (assoc_comments_text parent module_list) rf.rf_text)
+        (fun rf -> rf.rf_text <- ao (assoc_comments_info parent module_list) rf.rf_text)
         fl
   );
   t
diff --git a/ocamldoc/odoc_html.ml b/ocamldoc/odoc_html.ml
index a35df03b99..db7d82ce16 100644
--- a/ocamldoc/odoc_html.ml
+++ b/ocamldoc/odoc_html.ml
@@ -1530,7 +1530,7 @@ class html =
                  bs b "(*";
                  bs b "</code></td>";
                  bs b "<td class=\"typefieldcomment\" align=\"left\" valign=\"top\" >";
-                 self#html_of_text b t;
+                 self#html_of_info b (Some t);
                  bs b "</td>";
                  bs b "<td class=\"typefieldcomment\" align=\"left\" valign=\"bottom\" >";
                  bs b "<code>";
@@ -1573,7 +1573,7 @@ class html =
                  bs b "(*";
                  bs b "</code></td>";
                  bs b "<td class=\"typefieldcomment\" align=\"left\" valign=\"top\" >";
-                 self#html_of_text b t;
+                 self#html_of_info b (Some t);
                  bs b "</td><td class=\"typefieldcomment\" align=\"left\" valign=\"bottom\" >";
                  bs b "<code>*)</code></td>";
             );
diff --git a/ocamldoc/odoc_info.mli b/ocamldoc/odoc_info.mli
index ae888300e6..bf4d33b6f6 100644
--- a/ocamldoc/odoc_info.mli
+++ b/ocamldoc/odoc_info.mli
@@ -203,7 +203,7 @@ module Type :
           vc_name : string ; (** Name of the constructor. *)
           vc_args : Types.type_expr list ; (** Arguments of the constructor. *)
           vc_ret : Types.type_expr option ;
-          mutable vc_text : text option ; (** Optional description in the associated comment. *)
+          mutable vc_text : info option ; (** Optional description in the associated comment. *)
         }
 
     (** Description of a record type field. *)
@@ -212,7 +212,7 @@ module Type :
           rf_name : string ; (** Name of the field. *)
           rf_mutable : bool ; (** [true] if mutable. *)
           rf_type : Types.type_expr ; (** Type of the field. *)
-          mutable rf_text : text option ; (** Optional description in the associated comment.*)
+          mutable rf_text : info option ; (** Optional description in the associated comment.*)
         }
 
     (** The various kinds of a type. *)
diff --git a/ocamldoc/odoc_latex.ml b/ocamldoc/odoc_latex.ml
index 7d026f46d0..90dba5fa3f 100644
--- a/ocamldoc/odoc_latex.ml
+++ b/ocamldoc/odoc_latex.ml
@@ -584,7 +584,7 @@ class latex =
                     | Some t ->
                         let s =
                           ps fmt2 "\\begin{ocamldoccomment}\n";
-                          self#latex_of_text fmt2 t;
+                          self#latex_of_info fmt2 (Some t);
                           ps fmt2 "\n\\end{ocamldoccomment}\n";
                           flush2 ()
                         in
@@ -612,7 +612,7 @@ class latex =
                       | Some t ->
                           let s =
                             ps fmt2 "\\begin{ocamldoccomment}\n";
-                            self#latex_of_text fmt2 t;
+                            self#latex_of_info fmt2 (Some t);
                             ps fmt2 "\n\\end{ocamldoccomment}\n";
                             flush2 ()
                         in
diff --git a/ocamldoc/odoc_man.ml b/ocamldoc/odoc_man.ml
index 7e01f8d4fb..8081369681 100644
--- a/ocamldoc/odoc_man.ml
+++ b/ocamldoc/odoc_man.ml
@@ -29,6 +29,8 @@ let new_buf () = Buffer.create 1024
 let bp = Printf.bprintf
 let bs = Buffer.add_string
 
+let linebreak = "\n.sp\n";;
+
 (** A class used to get a [text] for info structures. *)
 class virtual info =
   object (self)
@@ -40,170 +42,193 @@ class virtual info =
     (** Return man code for a [text]. *)
     method virtual man_of_text : Buffer.t -> Odoc_info.text -> unit
 
+    method str_man_of_text t =
+      let b = Buffer.create 256 in
+      self#man_of_text b t ;
+      Buffer.contents b
+
     (** Print groff string for an author list. *)
-    method man_of_author_list b l =
+    method str_man_of_author_list l =
       match l with
-        [] -> ()
+        [] -> ""
       | _ ->
+          let b = Buffer.create 256 in
           bs b ".B \"";
           bs b Odoc_messages.authors;
           bs b "\"\n:\n";
           bs b (String.concat ", " l);
-          bs b "\n.sp\n"
+          bs b "\n";
+          (*bs b "\n.sp\n"*)
+          Buffer.contents b
 
     (** Print groff string for the given optional version information.*)
-    method man_of_version_opt b v_opt =
+    method str_man_of_version_opt v_opt =
       match v_opt with
-        None -> ()
+        None -> ""
       | Some v ->
+          let b = Buffer.create 256 in
           bs b ".B \"";
           bs b Odoc_messages.version;
           bs b "\"\n:\n";
           bs b v;
-          bs b "\n.sp\n"
+          bs b "\n";
+          (*".sp\n"*)
+          Buffer.contents b
 
     (** Printf groff string for the \@before information. *)
-    method man_of_before b = function
-      [] -> ()
+    method str_man_of_before = function
+      [] -> ""
     | l ->
-        List.iter
-          (fun (v, text) ->
+        let b = Buffer.create 256 in
+        let rec iter = function
+          [] -> ()
+        | (v, text) :: q ->
              bp b ".B \"%s" Odoc_messages.before;
              bs b v;
              bs b "\"\n";
              self#man_of_text b text;
              bs b "\n";
-             bs b "\n.sp\n"
-          )
-          l
-
+             bs b "\n";
+             match q with
+               [] -> ()
+             | _ -> bs b linebreak ; iter q
+        in
+        iter l;
+        Buffer.contents b
 
     (** Print groff string for the given optional since information.*)
-    method man_of_since_opt b s_opt =
+    method str_man_of_since_opt s_opt =
       match s_opt with
-        None -> ()
+        None -> ""
       | Some s ->
+          let b = Buffer.create 256 in
           bs b ".B \"";
           bs b Odoc_messages.since;
           bs b "\"\n";
           bs b s;
-          bs b "\n.sp\n"
+          bs b "\n";(*".sp\n"*)
+          Buffer.contents b
 
     (** Print groff string for the given list of raised exceptions.*)
-    method man_of_raised_exceptions b l =
+    method str_man_of_raised_exceptions l =
       match l with
-        [] -> ()
-      | (s, t) :: [] ->
-          bs b ".B \"";
-          bs b Odoc_messages.raises;
-          bs b (" "^s^"\"\n");
-          self#man_of_text b t;
-          bs b "\n.sp\n"
+        [] -> ""
       | _ ->
-          bs b ".B \"";
-          bs b Odoc_messages.raises;
-          bs b "\"\n";
-          List.iter
-            (fun (ex, desc) ->
-              bs b ".sp\n.B \"";
-              bs b ex;
-              bs b "\"\n";
-              self#man_of_text b desc;
-              bs b "\n"
-            )
-            l;
-          bs b "\n.sp\n"
+          let b = Buffer.create 256 in
+          let rec iter = function
+            [] -> ()
+          | (s, t) :: q ->
+              bs b ".B \"";
+              bs b Odoc_messages.raises;
+              bs b (" "^s^"\"\n");
+              self#man_of_text b t;
+              bs b "\n";
+              match q with
+                [] -> ()
+              | _ -> bs b linebreak; iter q
+          in
+          iter l;
+          Buffer.contents b
 
     (** Print groff string for the given "see also" reference. *)
-    method man_of_see b (see_ref, t)  =
+    method str_man_of_see (see_ref, t)  =
       let t_ref =
         match see_ref with
           Odoc_info.See_url s -> [ Odoc_info.Link (s, t) ]
         | Odoc_info.See_file s -> (Odoc_info.Code s) :: (Odoc_info.Raw " ") :: t
         | Odoc_info.See_doc s -> (Odoc_info.Italic [Odoc_info.Raw s]) :: (Odoc_info.Raw " ") :: t
       in
-      self#man_of_text b t_ref
+      self#str_man_of_text t_ref
 
     (** Print groff string for the given list of "see also" references.*)
-    method man_of_sees b l =
+    method str_man_of_sees l =
       match l with
-        [] -> ()
-      | see :: [] ->
-          bs b ".B \"";
-          bs b Odoc_messages.see_also;
-          bs b "\"\n";
-          self#man_of_see b see;
-          bs b "\n.sp\n"
+        [] -> ""
       | _ ->
-          bs b ".B \"";
-          bs b Odoc_messages.see_also;
-          bs b "\"\n";
-          List.iter
-            (fun see ->
-              bs b ".sp\n";
-              self#man_of_see b see;
-              bs b "\n"
-            )
-            l;
-          bs b "\n.sp\n"
+          let b = Buffer.create 256 in
+          let rec iter = function
+            [] -> ()
+          | see :: q ->
+              bs b ".B \"";
+              bs b Odoc_messages.see_also;
+              bs b "\"\n";
+              bs b (self#str_man_of_see see);
+              bs b "\n";
+              match q with
+                [] -> ()
+              | _ -> bs b linebreak; iter q
+          in
+          iter l;
+          Buffer.contents b
 
     (** Print groff string for the given optional return information.*)
-    method man_of_return_opt b return_opt =
+    method str_man_of_return_opt return_opt =
       match return_opt with
-        None -> ()
+        None -> ""
       | Some s ->
+          let b = Buffer.create 256 in
           bs b ".B ";
           bs b Odoc_messages.returns;
           bs b "\n";
           self#man_of_text b s;
-          bs b "\n.sp\n"
+          bs b "\n";
+          Buffer.contents b
 
     (** Print man code for the given list of custom tagged texts. *)
-    method man_of_custom b l =
-      let buf = Buffer.create 50 in
-      List.iter
-        (fun (tag, text) ->
-          try
-            let f = List.assoc tag tag_functions in
-            Buffer.add_string buf (f text)
+    method str_man_of_custom l =
+      List.fold_left
+        (fun acc (tag, text) ->
+           try
+             let f = List.assoc tag tag_functions in
+             let buf = Buffer.create 50 in
+             Buffer.add_string buf (f text);
+             (Buffer.contents buf) :: acc
           with
             Not_found ->
-              Odoc_info.warning (Odoc_messages.tag_not_handled tag)
+              Odoc_info.warning (Odoc_messages.tag_not_handled tag);
+              acc
         )
-        l
+        [] l
 
     (** Print the groff string to display an optional info structure. *)
-    method man_of_info b info_opt =
+    method man_of_info ?(margin=0) b info_opt =
         match info_opt with
         None -> ()
       | Some info ->
           let module M = Odoc_info in
-          (
+          let l =
+            (
            match info.M.i_deprecated with
-             None -> ()
+             None -> []
            | Some d ->
+               let b = Buffer.create 256 in
                bs b ".B \"";
                bs b Odoc_messages.deprecated;
                bs b "\"\n";
                self#man_of_text b d;
-               bs b "\n.sp\n"
-          );
-          (
-           match info.M.i_desc with
-             None -> ()
-           | Some d when d = [Odoc_info.Raw ""] -> ()
-           | Some d ->
-               self#man_of_text b d;
-               bs b "\n.sp\n"
-          );
-          self#man_of_author_list b info.M.i_authors;
-          self#man_of_version_opt b info.M.i_version;
-          self#man_of_before b info.M.i_before;
-          self#man_of_since_opt b info.M.i_since;
-          self#man_of_raised_exceptions b info.M.i_raised_exceptions;
-          self#man_of_return_opt b info.M.i_return_value;
-          self#man_of_sees b info.M.i_sees;
-          self#man_of_custom b info.M.i_custom
+               bs b "\n";
+               [ Buffer.contents b ]
+            ) @
+              (
+               match info.M.i_desc with
+                 None -> []
+               | Some d when d = [Odoc_info.Raw ""] -> []
+               | Some d ->
+                   [ (self#str_man_of_text d)^"\n" ]
+              ) @
+              [
+                self#str_man_of_author_list info.M.i_authors;
+                self#str_man_of_version_opt info.M.i_version;
+                self#str_man_of_before info.M.i_before;
+                self#str_man_of_since_opt info.M.i_since;
+                self#str_man_of_raised_exceptions info.M.i_raised_exceptions;
+                self#str_man_of_return_opt info.M.i_return_value;
+                self#str_man_of_sees info.M.i_sees;
+              ] @
+                (self#str_man_of_custom info.M.i_custom)
+          in
+          let l = List.filter ((<>) "") l in
+          Buffer.add_string b (String.concat "\n.sp\n" l)
   end
 
 module Generator =
@@ -463,9 +488,9 @@ class man =
                match constr.vc_args, constr.vc_text,constr.vc_ret with
                | [], None, None -> bs b "\n "
                | [], (Some t), None ->
-                   bs b "  (* ";
-                   self#man_of_text b t;
-                   bs b " *)\n "
+                   bs b "  (*\n";
+                   self#man_of_info b (Some t);
+                   bs b "*)\n "
                | l, None, None ->
                    bs b "\n.B of ";
                    self#man_of_type_expr_list ~par: false b father " * " l;
@@ -474,9 +499,9 @@ class man =
                    bs b "\n.B of ";
                    self#man_of_type_expr_list ~par: false b father " * " l;
                    bs b ".I \"  \"\n";
-                   bs b "(* ";
-                   self#man_of_text b t;
-                   bs b " *)\n "
+                   bs b "(*\n";
+                   self#man_of_info b (Some t);
+                   bs b "*)\n"
                | [], None, Some r ->
                    bs b "\n.B : ";
                    self#man_of_type_expr b father r;
@@ -485,9 +510,9 @@ class man =
                    bs b "\n.B : ";
                    self#man_of_type_expr b father r;
                    bs b ".I \"  \"\n";
-                   bs b "(* ";
-                   self#man_of_text b t;
-                   bs b " *)\n "
+                   bs b "(*\n";
+                   self#man_of_info b (Some t);
+                   bs b "*)\n "
                | l, None, Some r ->
                    bs b "\n.B : ";
                    self#man_of_type_expr_list ~par: false b father " * " l;
@@ -500,9 +525,9 @@ class man =
                    bs b ".B -> ";
                    self#man_of_type_expr b father r;
                    bs b ".I \"  \"\n";
-                   bs b "(* ";
-                   self#man_of_text b t;
-                   bs b " *)\n "
+                   bs b "(*\n";
+                   self#man_of_info b (Some t);
+                   bs b "*)\n "
               )
             )
             l
@@ -520,9 +545,9 @@ class man =
                match r.rf_text with
                  None -> ()
                | Some t ->
-                   bs b "  (* ";
-                   self#man_of_text b t;
-                   bs b " *) "
+                   bs b "  (*\n";
+                   self#man_of_info b (Some t);
+                   bs b "*) "
               );
             )
             l;
diff --git a/ocamldoc/odoc_merge.ml b/ocamldoc/odoc_merge.ml
index 1e94c27377..eda6491ec9 100644
--- a/ocamldoc/odoc_merge.ml
+++ b/ocamldoc/odoc_merge.ml
@@ -245,7 +245,7 @@ let merge_types merge_options mli ml =
             | None, Some d -> Some d
             | Some d1, Some d2 ->
                 if List.mem Merge_description merge_options then
-                  Some (d1 @ d2)
+                  Some (merge_info merge_options d1 d2)
                 else
                   Some d1
           in
@@ -273,7 +273,7 @@ let merge_types merge_options mli ml =
             | None, Some d -> Some d
             | Some d1, Some d2 ->
                 if List.mem Merge_description merge_options then
-                  Some (d1 @ d2)
+                  Some (merge_info merge_options d1 d2)
                 else
                   Some d1
           in
diff --git a/ocamldoc/odoc_sig.ml b/ocamldoc/odoc_sig.ml
index 6f6eaedf12..422b355078 100644
--- a/ocamldoc/odoc_sig.ml
+++ b/ocamldoc/odoc_sig.ml
@@ -222,10 +222,7 @@ module Analyser =
           let f {Types.cd_id=constructor_name;cd_args=type_expr_list;cd_res=ret_type} =
             let constructor_name = Ident.name constructor_name in
             let comment_opt =
-              try
-                match List.assoc constructor_name name_comment_list with
-                  None -> None
-                | Some d -> d.Odoc_types.i_desc
+              try List.assoc constructor_name name_comment_list 
               with Not_found -> None
             in
             {
@@ -241,10 +238,7 @@ module Analyser =
           let f {Types.ld_id=field_name;ld_mutable=mutable_flag;ld_type=type_expr} =
             let field_name = Ident.name field_name in
             let comment_opt =
-              try
-                match List.assoc field_name name_comment_list with
-                  None -> None
-                | Some d -> d.Odoc_types.i_desc
+              try List.assoc field_name name_comment_list
               with Not_found -> None
             in
             {
diff --git a/ocamldoc/odoc_str.ml b/ocamldoc/odoc_str.ml
index b36ad95965..3c45c50705 100644
--- a/ocamldoc/odoc_str.ml
+++ b/ocamldoc/odoc_str.ml
@@ -201,7 +201,7 @@ let string_of_type t =
                 None ->
                   ""
               | Some t ->
-                  "(* "^(Odoc_misc.string_of_text t)^" *)"
+                  "(* "^(Odoc_misc.string_of_info t)^" *)"
               )^"\n"
             )
             l
@@ -219,7 +219,7 @@ let string_of_type t =
                 None ->
                   ""
               | Some t ->
-                  "(* "^(Odoc_misc.string_of_text t)^" *)"
+                  "(* "^(Odoc_misc.string_of_info t)^" *)"
               )^"\n"
             )
             l
diff --git a/ocamldoc/odoc_texi.ml b/ocamldoc/odoc_texi.ml
index 067586b826..95354caac8 100644
--- a/ocamldoc/odoc_texi.ml
+++ b/ocamldoc/odoc_texi.ml
@@ -676,8 +676,8 @@ class texi =
                        (match constr.vc_text with
                        | None -> [ Newline ]
                        | Some t ->
-                           (Raw (indent 5 "\n(* ") ::
-                            self#soft_fix_linebreaks 8 t) @
+                           (Raw (indent 5 "\n(*\n ") ::
+                            self#soft_fix_linebreaks 8 (self#text_of_info (Some t))) @
                            [ Raw " *)" ; Newline ]
                        ) ) l ) )
            | Type_record l ->
@@ -693,7 +693,8 @@ class texi =
                        (match r.rf_text with
                        | None -> [ Newline ]
                        | Some t ->
-                           ((Raw (indent 5 "\n(* ")) :: (self#soft_fix_linebreaks 8 t)) @
+                           ((Raw (indent 5 "\n(*\n ")) ::
+                           (self#soft_fix_linebreaks 8 (self#text_of_info (Some t)))) @
                            [ Raw " *)" ; Newline ] ) )
                      l ) )
                @  [ Raw " }" ]
diff --git a/ocamldoc/odoc_type.ml b/ocamldoc/odoc_type.ml
index fefd007c86..ef9699e607 100644
--- a/ocamldoc/odoc_type.ml
+++ b/ocamldoc/odoc_type.ml
@@ -22,7 +22,7 @@ type variant_constructor = {
     vc_name : string ;
     vc_args : Types.type_expr list ; (** arguments of the constructor *)
     vc_ret : Types.type_expr option ;
-    mutable vc_text : Odoc_types.text option ; (** optional user description *)
+    mutable vc_text : Odoc_types.info option ; (** optional user description *)
   }
 
 (** Description of a record type field. *)
@@ -30,7 +30,7 @@ type record_field = {
     rf_name : string ;
     rf_mutable : bool ; (** true if mutable *)
     rf_type : Types.type_expr ;
-    mutable rf_text : Odoc_types.text option ; (** optional user description *)
+    mutable rf_text : Odoc_types.info option ; (** optional user description *)
   }
 
 (** The various kinds of type. *)