Adding ocamldoc-style comments for the Ocaml bindings.

git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@44494 91177308-0d34-0410-b5e6-96231b3b80d8

Author: Gordon Henriksen

bindings/ocaml/analysis/llvm_analysis.ml

@@ -5,11 +5,6 @@
  * This file was developed by Gordon Henriksen and is distributed under the
  * University of Illinois Open Source License. See LICENSE.TXT for details.
  *
- *===----------------------------------------------------------------------===
- *
- * This interface provides an ocaml API for LLVM IR analyses, the classes in
- * the Analysis library.
- *
  *===----------------------------------------------------------------------===*)
 
 

bindings/ocaml/analysis/llvm_analysis.mli

@@ -13,12 +13,24 @@
  *===----------------------------------------------------------------------===*)
 
 
+(** [verify_module m] returns [None] if the module [m] is valid, and
+    [Some reason] if it is invalid. [reason] is a string containing a
+    human-readable validation report. See [llvm::verifyModule]. **)
 external verify_module : Llvm.llmodule -> string option = "llvm_verify_module"
 
+(** [verify_function f] returns [None] if the function [f] is valid, and
+    [Some reason] if it is invalid. [reason] is a string containing a
+    human-readable validation report. See [llvm::verifyFunction]. **)
 external verify_function : Llvm.llvalue -> bool = "llvm_verify_function"
 
+(** [verify_module m] returns if the module [m] is valid, but prints a
+    validation report to [stderr] and aborts the program if it is invalid. See 
+    [llvm::verifyModule]. **)
 external assert_valid_module : Llvm.llmodule -> unit
                              = "llvm_assert_valid_module"
 
+(** [verify_function f] returns if the function [f] is valid, but prints a
+    validation report to [stderr] and aborts the program if it is invalid. See 
+    [llvm::verifyFunction]. **)
 external assert_valid_function : Llvm.llvalue -> unit
                                = "llvm_assert_valid_function"

bindings/ocaml/bitwriter/llvm_bitwriter.mli

@@ -13,6 +13,7 @@
  *===----------------------------------------------------------------------===*)
 
 
-(* Writes the bitcode for module the given path. Returns true if successful. *)
+(** [write_bitcode_file m path] writes the bitcode for module [m] to the file at
+    [path]. Returns [true] if successful, [false] otherwise. **)
 external write_bitcode_file : Llvm.llmodule -> string -> bool
                             = "llvm_write_bitcode_file"

bindings/ocaml/llvm/llvm.ml

@@ -5,21 +5,14 @@
  * This file was developed by Gordon Henriksen and is distributed under the
  * University of Illinois Open Source License. See LICENSE.TXT for details.
  *
- *===----------------------------------------------------------------------===
- *
- * This interface provides an ocaml API for the LLVM intermediate
- * representation, the classes in the VMCore library.
- *
  *===----------------------------------------------------------------------===*)
 
 
-(* These abstract types correlate directly to the LLVM VMCore classes. *)
 type llmodule
 type lltype
 type lltypehandle
 type llvalue
-type llbasicblock (* These are actually values, but
-                     benefit from type checking. *)
+type llbasicblock
 type llbuilder
 
 type type_kind =
@@ -93,28 +86,17 @@ type real_predicate =
 
 (*===-- Modules -----------------------------------------------------------===*)
 
-(* Creates a module with the supplied module ID. Modules are not garbage
-   collected; it is mandatory to call dispose_module to free memory. *)
 external create_module : string -> llmodule = "llvm_create_module"
-
-(* Disposes a module. All references to subordinate objects are invalidated;
-   referencing them will invoke undefined behavior. *)
 external dispose_module : llmodule -> unit = "llvm_dispose_module"
-
-(* Adds a named type to the module's symbol table. Returns true if successful.
-   If such a name already exists, then no entry is added and returns false. *)
 external define_type_name : string -> lltype -> llmodule -> bool
                           = "llvm_add_type_name"
-
 external delete_type_name : string -> llmodule -> unit
                           = "llvm_delete_type_name"
 
 
 (*===-- Types -------------------------------------------------------------===*)
 
 external classify_type : lltype -> type_kind = "llvm_classify_type"
-external refine_abstract_type : lltype -> lltype -> unit
-                              = "llvm_refine_abstract_type"
 
 (*--... Operations on integer types ........................................--*)
 external _i1_type : unit -> lltype = "llvm_i1_type"
@@ -146,7 +128,6 @@ let fp128_type = _fp128_type ()
 let ppc_fp128_type = _ppc_fp128_type ()
 
 (*--... Operations on function types .......................................--*)
-(* FIXME: handle parameter attributes *)
 external function_type : lltype -> lltype array -> lltype = "llvm_function_type"
 external var_arg_function_type : lltype -> lltype array -> lltype
                                = "llvm_var_arg_function_type"
@@ -280,6 +261,7 @@ external define_global : string -> llvalue -> llmodule -> llvalue
 external lookup_global : string -> llmodule -> llvalue option
                        = "llvm_lookup_global"
 external delete_global : llvalue -> unit = "llvm_delete_global"
+external has_initializer : llvalue -> bool = "llvm_has_initializer"
 external global_initializer : llvalue -> llvalue = "LLVMGetInitializer"
 external set_initializer : llvalue -> llvalue -> unit = "llvm_set_initializer"
 external remove_initializer : llvalue -> unit = "llvm_remove_initializer"
@@ -457,6 +439,7 @@ let concat2 sep arr =
   !s
 
 let rec string_of_lltype ty =
+  (* FIXME: stop infinite recursion! :) *)
   match classify_type ty with
     Integer_type -> "i" ^ string_of_int (integer_bitwidth ty)
   | Pointer_type -> (string_of_lltype (element_type ty)) ^ "*"