Modification emplacement et syntaxe commentaires pour OCamldoc

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

1 files changed, 84 insertions, 60 deletions

diff --git a/stdlib/int32.mli b/stdlib/int32.mli
index eaa5aee575..dbb1c2814b 100644
--- a/stdlib/int32.mli
+++ b/stdlib/int32.mli
@@ -12,9 +12,9 @@
 
 (* $Id$ *)
 
-(* Module [Int32]: 32-bit integers *)
+(** 32-bit integers.
 
-(* This module provides operations on the type [int32]
+   This module provides operations on the type [int32]
    of signed 32-bit integers.  Unlike the built-in [int] type,
    the type [int32] is guaranteed to be exactly 32-bit wide on all
    platforms.  All arithmetic operations over [int32] are taken
@@ -25,94 +25,118 @@
    [int32] are generally slower than those on [int].  Use [int32]
    only when the application requires exact 32-bit arithmetic. *)
 
+(** The 32-bit integer 0. *)
 val zero : int32
+
+(** The 32-bit integer 1. *)
 val one : int32
+
+(** The 32-bit integer -1. *)
 val minus_one : int32
-      (* The 32-bit integers 0, 1, -1. *)
 
+(** Unary negation. *)
 external neg : int32 -> int32 = "%int32_neg"
-      (* Unary negation. *)
+
+(** Addition. *)
 external add : int32 -> int32 -> int32 = "%int32_add"
-      (* Addition. *)
+
+(** Subtraction. *)
 external sub : int32 -> int32 -> int32 = "%int32_sub"
-      (* Subtraction. *)
+
+(** Multiplication. *)
 external mul : int32 -> int32 -> int32 = "%int32_mul"
-      (* Multiplication. *)
+
+(** Integer division.  Raise [Division_by_zero] if the second 
+   argument is zero. *)
 external div : int32 -> int32 -> int32 = "%int32_div"
-      (* Integer division.  Raise [Division_by_zero] if the second 
-         argument is zero. *)
+
+(** Integer remainder.  If [x >= 0] and [y > 0], the result
+   of [Int32.rem x y] satisfies the following properties:
+   [0 <= Int32.rem x y < y] and
+   [x = Int32.add (Int32.mul (Int32.div x y) y) (Int32.rem x y)].
+   If [y = 0], [Int32.rem x y] raises [Division_by_zero].
+   If [x < 0] or [y < 0], the result of [Int32.rem x y] is
+   not specified and depends on the platform. *)
 external rem : int32 -> int32 -> int32 = "%int32_mod"
-      (* Integer remainder.  If [x >= 0] and [y > 0], the result
-           of [Int32.rem x y] satisfies the following properties:
-           [0 <= Int32.rem x y < y] and
-           [x = Int32.add (Int32.mul (Int32.div x y) y) (Int32.rem x y)].
-           If [y = 0], [Int32.rem x y] raises [Division_by_zero].
-           If [x < 0] or [y < 0], the result of [Int32.rem x y] is
-           not specified and depends on the platform. *)
+
+(** Successor.  [Int32.succ x] is [Int32.add x Int32.one]. *)
 val succ : int32 -> int32
-      (* Successor.  [Int32.succ x] is [Int32.add x Int32.one]. *)
+
+(** Predecessor.  [Int32.pred x] is [Int32.sub x Int32.one]. *)
 val pred : int32 -> int32
-      (* Predecessor.  [Int32.pred x] is [Int32.sub x Int32.one]. *)
+
+(** Return the absolute value of its argument. *)
 val abs : int32 -> int32
-      (* Return the absolute value of its argument. *)
+
+(** The greatest representable 32-bit integer, $2^{31} - 1$. *)
 val max_int : int32
-      (* The greatest representable 32-bit integer, $2^{31} - 1$. *)
+
+(** The smallest representable 32-bit integer, $-2^{31}$. *)
 val min_int : int32
-      (* The smallest representable 32-bit integer, $-2^{31}$. *)
 
+
+(** Bitwise logical and. *)
 external logand : int32 -> int32 -> int32 = "%int32_and"
-      (* Bitwise logical and. *)
+
+(** Bitwise logical or. *)
 external logor : int32 -> int32 -> int32 = "%int32_or"
-      (* Bitwise logical or. *)
+
+(** Bitwise logical exclusive or. *)
 external logxor : int32 -> int32 -> int32 = "%int32_xor"
-      (* Bitwise logical exclusive or. *)
+
+(** Bitwise logical negation *)
 val lognot : int32 -> int32
-      (* Bitwise logical negation *)
+
+(** [Int32.shift_left x y] shifts [x] to the left by [y] bits.
+   The result is unspecified if [y < 0] or [y >= 32]. *)
 external shift_left : int32 -> int -> int32 = "%int32_lsl"
-      (* [Int32.shift_left x y] shifts [x] to the left by [y] bits.
-         The result is unspecified if [y < 0] or [y >= 32]. *)
+
+(** [Int32.shift_right x y] shifts [x] to the right by [y] bits.
+   This is an arithmetic shift: the sign bit of [x] is replicated
+   and inserted in the vacated bits.
+   The result is unspecified if [y < 0] or [y >= 32]. *)
 external shift_right : int32 -> int -> int32 = "%int32_asr"
-      (* [Int32.shift_right x y] shifts [x] to the right by [y] bits.
-         This is an arithmetic shift: the sign bit of [x] is replicated
-         and inserted in the vacated bits.
-         The result is unspecified if [y < 0] or [y >= 32]. *)
+
+(** [Int32.shift_right_logical x y] shifts [x] to the right by [y] bits.
+   This is a logical shift: zeroes are inserted in the vacated bits
+   regardless of the sign of [x].
+   The result is unspecified if [y < 0] or [y >= 32]. *)
 external shift_right_logical : int32 -> int -> int32 = "%int32_lsr"
-      (* [Int32.shift_right_logical x y] shifts [x] to the right by [y] bits.
-         This is a logical shift: zeroes are inserted in the vacated bits
-         regardless of the sign of [x].
-         The result is unspecified if [y < 0] or [y >= 32]. *)
 
+(** Convert the given integer (type [int]) to a 32-bit integer (type [int32]). *)
 external of_int : int -> int32 = "%int32_of_int"
-      (* Convert the given integer (type [int]) to a 32-bit integer
-         (type [int32]). *)
+
+(** Convert the given 32-bit integer (type [int32]) to an
+   integer (type [int]).  On 32-bit platforms, the 32-bit integer
+   is taken modulo $2^{31}$, i.e. the high-order bit is lost
+   during the conversion.  On 64-bit platforms, the conversion
+   is exact. *)
 external to_int : int32 -> int = "%int32_to_int"
-      (* Convert the given 32-bit integer (type [int32]) to an
-         integer (type [int]).  On 32-bit platforms, the 32-bit integer
-         is taken modulo $2^{31}$, i.e. the high-order bit is lost
-         during the conversion.  On 64-bit platforms, the conversion
-         is exact. *)
 
+(** Convert the given floating-point number to a 32-bit integer,
+   discarding the fractional part (truncate towards 0).
+   The result of the conversion is undefined if, after truncation,
+   the number is outside the range \[{!Int32.min_int}, {!Int32.max_int}\]. *)
 external of_float : float -> int32 = "int32_of_float"
-      (* Convert the given floating-point number to a 32-bit integer,
-         discarding the fractional part (truncate towards 0).
-         The result of the conversion is undefined if, after truncation,
-         the number is outside the range [Int32.min_int, Int32.max_int]. *)
+
+(** Convert the given 32-bit integer to a floating-point number. *)
 external to_float : int32 -> float = "int32_to_float"
-      (* Convert the given 32-bit integer to a floating-point number. *)
 
+(** Convert the given string to a 32-bit integer.
+   The string is read in decimal (by default) or in hexadecimal,
+   octal or binary if the string begins with [0x], [0o] or [0b]
+   respectively.
+   Raise [Failure "int_of_string"] if the given string is not
+   a valid representation of an integer. *)
 external of_string : string -> int32 = "int32_of_string"
-      (* Convert the given string to a 32-bit integer.
-         The string is read in decimal (by default) or in hexadecimal,
-         octal or binary if the string begins with [0x], [0o] or [0b]
-         respectively.
-         Raise [Failure "int_of_string"] if the given string is not
-         a valid representation of an integer. *)
+
+(** Return the string representation of its argument, in signed decimal. *)
 val to_string : int32 -> string
-      (* Return the string representation of its argument,
-         in signed decimal. *)
+
+(** [Int32.format fmt n] return the string representation of the
+   32-bit integer [n] in the format specified by [fmt].
+   [fmt] is a [Printf]-style format containing exactly
+   one [%d], [%i], [%u], [%x], [%X] or [%o] conversion specification.
+   See the documentation of the [Printf] module for more information, *)
 external format : string -> int32 -> string = "int32_format"
-      (* [Int32.format fmt n] return the string representation of the
-         32-bit integer [n] in the format specified by [fmt].
-         [fmt] is a [Printf]-style format containing exactly
-         one [%d], [%i], [%u], [%x], [%X] or [%o] conversion specification.
-         See the documentation of the [Printf] module for more information, *)
+