Merge pull request #53 from mbarbin/fix-odoc-warnings

Fix (some) odoc warnings

lib/miou.mli

@@ -332,7 +332,7 @@
       Exception: Miou.Still_has_children.
     ]}
 
-    {4:rule-2 Rule 2, only await for direct children.}
+    {4:rule_2 Rule 2, only await for direct children.}
 
     You can only await for your direct children. Transferring a promise to
     another task so that it can await for it is illegal:
@@ -420,8 +420,8 @@
     The advantage of making suspension points local to domains is that the
     domain is solely responsible for these points and there are no inter-domain
     transfer mechanisms for managing system events. For the example,
-    {!module:Domain.DLS} can be used for a table of current events in each
-    domain.
+    {!module:Stdlib.Domain.DLS} can be used for a table of current events in
+    each domain.
 
     {[
       let get, set =
@@ -682,7 +682,7 @@ val care : 'a orphans -> 'a t option option
       that promise in an orphanage. So, if [care] is used elsewhere than in the
       promise, an exception is raised to warn the user of a misuse of [care].
       Indeed, the child returned by care can only be awaited ({!await}) by its
-      direct parent (in reference to {{!section:rule-2}our second rule}). *)
+      direct parent (in reference to {{!section:rule_2}our second rule}). *)
 
 val length : _ orphans -> int
 (** [length orphans] returns the number of remaining tasks. *)
@@ -1143,8 +1143,8 @@ val protect :
     [finally] raises an exception, then the exception {!Fun.Finally_raised} is
     raised instead. In the case of a cancellation, it invokes [finally ()] and
     then [on_cancellation ()] before the deletion of [fn ()]. If
-    [on_cancellation ()] raises an exception, then the exception
-    {!On_cancellation_raised} is raised instead.
+    [on_cancellation ()] raises an exception, then the "uncatchable" exception
+    [On_cancellation_raised] is raised instead.
 
     [on_cancellation] must {b not} use any effects. Using effects suspends
     execution and, in the case of cancellation, anything after the effect will
@@ -1172,7 +1172,7 @@ module Mutex : sig
       will restart. The mutex must have been previously locked by the thread
       that calls {!val:unlock}.
 
-      @raise Sysy_error
+      @raise Sys_error
         was not raised when unlocking an unlocked mutex or when unlocking a
         mutex from a different task. *)
 

lib/miou_state.mli

@@ -16,7 +16,7 @@ type error = exn * Printexc.raw_backtrace
     In the case of a suspension, the user can "continue" the execution via what
     is expected by the associated effect. Note that {!val:once} can only be used
     {b once} on a given value {!type:t} (otherwise, an exception
-    {!exception:Continuation_already_resumed} is raised by OCaml). *)
+    {!exception:Effect.Continuation_already_resumed} is raised by OCaml). *)
 type 'a t = private
   | Finished of ('a, error) result
   | Suspended : ('a, 'b) continuation * 'a Effect.t -> 'b t
@@ -60,8 +60,9 @@ val once : perform:perform -> 'a t -> 'a t
 val fail : backtrace:Printexc.raw_backtrace -> exn:exn -> 'a t -> 'a t
 (** [fail ~exn state] discontinues the given state with the given exception. It
     always return [Finished (Error exn)]. If the given state was already resumed
-    elsewhere, this function traps the exception [Continuation_already_resumed]
-    and return [Finished (Error exn)]. *)
+    elsewhere, this function traps the exception
+    {!exception:Effect.Continuation_already_resumed} and return
+    [Finished (Error exn)]. *)
 
 val pure : ('a, error) result -> 'a t
 (** [pure value] returns [Finished value]. *)
@@ -72,8 +73,8 @@ val run : quanta:int -> perform:perform -> 'a t -> 'a t
     nothing), even though there may be a few {i quanta} left, the function
     returns the last state obtained.
 
-    The same applies to {!val:yield}, except that the continuation has burnt
-    itself out. In other words, {!val:yield} is equivalent to
+    The same applies to {!val:Operation.yield}, except that the continuation has
+    burnt itself out. In other words, {!val:Operation.yield} is equivalent to
     [send (); interrupt] but costs only one {i quanta}. *)
 
 (**/**)

lib/miou_unix.mli

@@ -69,10 +69,10 @@ val read : file_descr -> ?off:int -> ?len:int -> bytes -> int
     [0]). It returns the actual number of characters read, between 0 and [len]
     (inclusive).
 
-    @raise Unix_error
+    @raise Unix.Unix_error
       raised by the system call {!val:Unix.read}. The function handles
-      {!val:Unix.EINTR}, {!val:Unix.EAGAIN} and {!val:Unix.EWOULDBLOCK}
-      exceptions and redo the system call.
+      {!constructor:Unix.EINTR}, {!constructor:Unix.EAGAIN} and
+      {!constructor:Unix.EWOULDBLOCK} exceptions and redo the system call.
 
     @raise Invalid_argument
       if [off] and [len] do not designate a valid range of [buf] *)
@@ -83,10 +83,10 @@ val really_read : file_descr -> ?off:int -> ?len:int -> bytes -> unit
     in byte sequence [buf], starting at position [off] in [buf] (defaults to
     [0]). If [len = 0], [really_read] does nothing.
 
-    @raise Unix_error
+    @raise Unix.Unix_error
       raised by the system call {!val:Unix.read}. The function handles
-      {!val:Unix.EINTR}, {!val:Unix.EAGAIN} and {!val:Unix.EWOULDBLOCK}
-      exceptions and redo the system call.
+      {!constructor:Unix.EINTR}, {!constructor:Unix.EAGAIN} and
+      {!constructor:Unix.EWOULDBLOCK} exceptions and redo the system call.
 
     @raise End_of_file
       if {!val:Unix.read} returns [0] before [len] characters have been read.
@@ -99,10 +99,10 @@ val write : file_descr -> ?off:int -> ?len:int -> string -> unit
     [String.length str - off]) from byte sequence [buf], starting at offset
     [off] (defaults to [0]), to the given file-descriptor [fd].
 
-    @raise Unix_error
+    @raise Unix.Unix_error
       raised by the system call {!val:Unix.read}. The function handles
-      {!val:Unix.EINTR}, {!val:Unix.EAGAIN} and {!val:Unix.EWOULDBLOCK}
-      exceptions and redo the system call.
+      {!constructor:Unix.EINTR}, {!constructor:Unix.EAGAIN} and
+      {!constructor:Unix.EWOULDBLOCK} exceptions and redo the system call.
 
     @raise Invalid_argument
       if [off] and [len] do not designate a valid range of [buf] *)

lib/miou_vector.mli

@@ -28,9 +28,9 @@
     Vectors provide an efficient implementation of stacks, with a
     better locality of reference than list-based implementations (such
     as standard library {!Stack}). A stack interface is provided,
-    similar to that of {!Stack} (though {!Vector.push} have arguments
+    similar to that of {!Stack} (though {!push} have arguments
     in the other way round). Inserting [n] elements with
-    {!Vector.push} has overall complexity O(n) i.e. each insertion has
+    {!push} has overall complexity O(n) i.e. each insertion has
     amortized constant time complexity. *)
 
 (*@ use List *)
@@ -219,7 +219,7 @@ val map : dummy:'b -> 'a t -> ('a -> 'b) -> 'b t
       ensures  forall i. 0 <= i < length a1.view -> a2.view[i] = f a1.view[i] *)
 
 val mapi : dummy:'b -> 'a t -> (int -> 'a -> 'b) -> 'b t
-(** Same as {!Vector.map}, but the
+(** Same as {!map}, but the
    function is applied to the index of the element as first argument,
    and the element itself as second argument.
 
@@ -264,15 +264,15 @@ val iter : ('a -> unit) -> 'a t -> unit
 *)
 
 val iteri : (int -> 'a -> unit) -> 'a t -> unit
-(** Same as {!Vector.iter}, but the
+(** Same as {!iter}, but the
    function is applied to the index of the element as first argument,
    and the element itself as second argument. *)
 (*@ iteri f a
       equivalent "for i = 0 to length a - 1 do f i (get a i) done" *)
 
 (** {2 Stack interface}
 
-    Contrary to standard library's {Stack}, module {Vector} uses less space
+    Contrary to standard library's {!Stack}, module [Vector] uses less space
     (between N and 2N words, instead of 3N) and has better data locality. *)
 
 val push: 'a t -> 'a -> unit