documentation fixes

index.mld

@@ -11,7 +11,7 @@ The following public components are included in the package:
 {!modules: Ast_check Test_lib Test_runner}
 
 {{!page-variants_and_overrides} [Stdlib] variants and overrides}:
-{!modules: Stdlib_alerts Stdlib_components Overrides}
+{!modules: Stdlib_alerts Stdlib_components Std_overrides}
 
 {1 Internal Components}
 

src/ast-check/ast_check.mli

@@ -80,7 +80,7 @@ val file_violations :
     [check] matches (default: [.ml] ending). Pass each (possibly empty) list of
     violations to the callback; see the note in {!pp_violation}.
 
-    The [follow] argument (default: {{!FilePath.Follow}[Follow]}) only applies to directories;
+    The [follow] argument (default: {{!FileUtil.Follow}[Follow]}) only applies to directories;
     symlinks to files are always read. *)
 val path_violations :
   ?follow:FileUtil.action_link ->

src/common/ctx_util.ml

@@ -2,12 +2,13 @@
 
 (** A context manager of type [('a, 'b, 'c) t] takes a continuation, and
     should feed the continuation a value of type ['a]. Once the continuation
-    returns with either a [Ok of 'b] or an {!exn_info}, the continuation should
-    perform cleanup, and may suppress the exception by producing a suitable
-    result (of type ['c]) instead. Often, ['b = 'c].
+    returns with either a ['b] (in {!Ok}) or an {{!Util.exn_info}[exn_info]} (in {!Error}),
+    the continuation should perform cleanup, and may suppress the exception by
+    producing a suitable result (of type ['c]) instead. Often, ['b = 'c].
 
-    This representation has the advantage that some existing functions library
-    already implement this type (e.g. {!In_channel.with_open_text}). *)
+    This representation has the advantage that existing context managers of
+    type [('a -> 'b) -> 'b] (where ['a] can be some concrete type like [unit])
+    already conform to this type (e.g. {!In_channel.with_open_text} and {!Mutex.protect}). *)
 type ('a, 'b, 'c) t = ('a -> ('b, Util.exn_info) result) -> ('c, Util.exn_info) result
 
 (** [with_context cm f] runs [f] in the context manager [cm] *)

src/common/util.ml

@@ -18,7 +18,7 @@ let uncons = function [] -> None | x :: xs -> Some (x, xs)
 
 let unsnoc xs = uncons (List.rev xs) |> Option.map (fun (x, xs) -> List.rev xs, x)
 
-(** Same as {!List.equal, but allows lists of different types} *)
+(** Same as {!List.equal}, but allows lists of different types *)
 let rec list_equal eq l1 l2 =
   match l1, l2 with
   | [], [] -> true

src/stdlib-variants/std-overrides/std_overrides.ml

@@ -31,7 +31,7 @@ module Stdlib_safe = struct
 end
 
 (** Puts an alerting [Stdlib] into scope,
-    from {!Stdlib_alerts.Stdlib_alerting}. *)
+    from {!Stdlib_alerts.module-type-Stdlib_alerting}. *)
 module Stdlib_alerting = struct
 
   module Stdlib = Stdlib_alerts.Stdlib_alerting

src/stdlib-variants/stdlib-alerts/stdlib_alerts.ml

@@ -1,6 +1,6 @@
 (** Variants of {!Stdlib}, but with signature items that can be restricted annotated with alerts.
 
-There is one "variant" of the {!Stdlib} interface implemented, namely {!Stdlib_alerting}.
+There is one "variant" of the {!Stdlib} interface implemented, namely {!module-type-Stdlib_alerting}.
 Alerts are placed on signature items (types, values, and modules) so that those items can be restricted.
 
 The following alerts are used:
@@ -16,7 +16,7 @@ By default, for a "safe" sandbox environment, the following alerts should be ena
 [physical_eq], [input_output], [impure], [unsafe]. The remaining alerts are intended for
 specific situtations and exercises where more needs to be restricted.
 
-Similar modules for {Thread} and {Event} are in {!Threads_alerts} to avoid unnecessary dependencies.
+Similar modules for [Thread] and [Event] are in {!Threads_alerts} to avoid unnecessary dependencies.
 *)
 
 [@@@alert "-physical_eq"]
@@ -182,7 +182,8 @@ module type Stdlib_alerting = sig
 
   [%%include stdlib.stdlib (( = ), ( <> ), ( < ), ( > ), ( <= ), ( >= ), compare, min, max) ]
 
-  (** {1 Physical comparisons} The impure [(==)] and [(!=)] *)
+  (** {1 Physical comparisons}
+      The impure [(==)] and [(!=)] *)
 
   [%%include
     {

src/stdlib-variants/variants_and_overrides.mld

@@ -19,7 +19,7 @@ Modules that are intended to be opened at the top level (what the compiler calls
 Usually this contains a module called [Stdlib], as well as the {i contents} of that module
 (e.g. via [open]). It may also contain e.g. a module called [Thread].
 
-{!modules: Overrides}
+{!modules: Std_overrides}
 
 {1 Implementation modules}
 

src/test-runner/task.ml

@@ -4,7 +4,7 @@
     building student code, checking for forbidden syntax elements, or
     running the generated test executable.
 
-    This module provides tasks as trees (type {!Tree.t}), so tasks can be
+    This module provides tasks as trees (type {!type-tree}), so tasks can be
     more easily re-used and composed.
 
     Running tasks automatically handles exceptions and timeouts.