Merge pull request #6150 from rjbou/mldoc-fixes

Some ocaml doc fixes

master_changes.md

@@ -119,11 +119,16 @@ users)
   * Fix debian manual url fragment [#6231 @RyanGibb]
   * Change example of non-letter in version ordering [#6252 @gridbugs]
   * Remove redundant `+` in version BNF definition (it is already present in `identchar`) [#6252 @rjbou]
+  * mli documentation: fix code blocks [#6150 @rjbou]
+  * mli documentation: fix code blocks, references [#6150 @rjbou]
+  * mli documentation: fix code blocks, references, add `@raise` tags [#6150 @rjbou]
+  * Unhide `OpamProcess` functions [#6150 @rjbou]
 
 ## Security fixes
 
 # API updates
 ## opam-client
+  * `OpamArg.InvalidCLI`: export exception [#6150 @rjbou]
 
 ## opam-repository
 

src/client/opamAction.mli

@@ -24,7 +24,7 @@ val download_package:
   rw switch_state -> package -> (string option * string) option OpamProcess.job
 
 (** [download_same_source_package t url packages]
-    As [download_package], download upstream shared source [url] between
+    As {!download_package}, download upstream shared source [url] between
     [packages]. *)
 val download_shared_source:
   rw switch_state -> OpamFile.URL.t option -> package list ->

src/client/opamArg.mli

@@ -90,7 +90,7 @@ val mk_vflag_all:
   (validity * 'a * string list * string) list ->
   'a list Term.t
 
-(* Escaped Windows directory separator. To use instead of [Filename.dir_sep] for
+(* Escaped Windows directory separator. To use instead of {!Filename.dir_sep} for
    manpage strings *)
 val dir_sep: string
 
@@ -318,7 +318,7 @@ val enum_with_default: (string * 'a default) list -> 'a Arg.converter
 val mk_subcommands_with_default:
   cli:OpamCLIVersion.Sourced.t ->
   'a default subcommands -> 'a option Term.t * string list Term.t
-(** Same as {!mk_subcommand} but use the default value if no
+(** Same as {!mk_subcommands} but use the default value if no
     sub-command is selected. *)
 
 val bad_subcommand:

src/client/opamArgTools.mli

@@ -60,7 +60,7 @@ val mk_enum_opt:
   cli:OpamCLIVersion.Sourced.t -> validity -> section:string -> string list ->
   string -> (validity * string * 'a) list -> string -> 'a option Term.t
 
-(** [opt_all] with enums. Check each flag content cli, purge non corresponding
+(** {!mk_opt_all} with enums. Check each flag content cli, purge non corresponding
     ones from the final result. If after purge the resulting list is empty (all
     removed or newer flag contents), it raises an error ; otherwise only
     display warnings on wrong cli contents. *)

src/client/opamAuxCommands.mli

@@ -20,8 +20,8 @@ open OpamStateTypes
     recorded package changes print warnings and aren't copied. *)
 val copy_files_to_destdir: 'a switch_state -> dirname -> package_set -> unit
 
-(** Removes all files that may have been installed by [copy_files_to_destdir];
-    it's more aggressive than [OpamDirTrack.revert] and doesn't check if the
+(** Removes all files that may have been installed by {!copy_files_to_destdir};
+    it's more aggressive than {!OpamDirTrack.revert} and doesn't check if the
     files are current. *)
 val remove_files_from_destdir: 'a switch_state -> dirname -> package_set -> unit
 
@@ -39,7 +39,7 @@ val opams_of_dir:
   ?locked:string -> ?recurse:bool -> ?subpath:subpath ->
   OpamFilename.Dir.t -> name_and_file list
 
-(** Like [opam_of_dirs], but changes the pinning_url if needed. If given [url]
+(** Like {!opams_of_dir}, but changes the pinning_url if needed. If given [url]
     is local dir with vcs backend, and opam files not versioned, its pinning url
     is changed to rsync path-pin. If [ame_kind the_new_url] returns true,
     package information (name, opam file, new_url, subpath) are added to the
@@ -107,7 +107,7 @@ val simulate_autopin:
   'a switch_state * atom list
 
 (* Check sandboxing script call. If it errors or unattended output, disable
-   sandboxing by removing [OpamInitDefaults.sandbox_wrappers] commands in
+   sandboxing by removing {!OpamInitDefaults.sandbox_wrappers} commands in
    config file.
    Only one script is checked (init script default one), and tested on an
    `echo SUCCESS' call. *)

src/client/opamCLIVersion.mli

@@ -26,7 +26,7 @@ val is_supported : t -> bool
 val of_string_opt : string -> t option
 val of_string : string -> t
 
-(** Comparison [>]] with [(major, minor)] *)
+(** Comparison [>=] with [(major, minor)] *)
 val ( >= ) : t -> int * int -> bool
 
 (** Comparison [<] with [(major, minor)] *)

src/client/opamCliMain.mli

@@ -8,6 +8,8 @@
 (*                                                                        *)
 (**************************************************************************)
 
+exception InvalidCLI of OpamCLIVersion.Sourced.t
+
 (** Handles calling opam plugins (à la git). E.g. [opam publish] runs
     [opam-publish] from PATH, with specific addition of OpamPath.plugins_bin and
     the current switch bin directory).
@@ -19,11 +21,11 @@ val check_and_run_external_commands:
   unit -> OpamCLIVersion.Sourced.t * string list
 
 (** Handles flushing buffers and catching exceptions from the main call,
-    including special cases like [OpamStd.Sys.Exec] that is expected to do a
-    [Unix.exec], but after all proper cleanup has been done. *)
+    including special cases like {!OpamStd.Sys.Exec} that is expected to do a
+    {!Unix.exec}, but after all proper cleanup has been done. *)
 val main_catch_all: (unit -> unit) -> unit
 
-(** Handling of debug JSON output, according to [OpamClientConfig.json_out] *)
+(** Handling of debug JSON output, according to {!OpamClientConfig.json_out} *)
 val json_out: unit -> unit
 
 (** [run default command_list] runs command-line argument parsing and processing

src/client/opamClient.mli

@@ -40,8 +40,8 @@ val init:
  *   OpamFile.InitConfig.t *)
 
 (** Re-runs the extra tools checks, updates the configuration from [init_config]
-   (defaults to [OpamInitDefaults.init_config]) for the settings that are unset,
-   and updates all repositories *)
+   (defaults to {!OpamInitDefaults.init_config}) for the settings that are
+   unset, and updates all repositories *)
 val reinit:
   ?init_config:OpamFile.InitConfig.t -> interactive:bool -> ?dot_profile:filename ->
   ?update_config:bool -> ?env_hook:bool -> ?completion:bool -> ?inplace:bool ->
@@ -62,7 +62,7 @@ val install:
   ?depext_only:bool -> atom list ->
   rw switch_state
 
-(** Low-level version of [reinstall], bypassing the package name sanitization
+(** Low-level version of {!reinstall}, bypassing the package name sanitization
     and dev package update, and offering more control *)
 val install_t:
   rw switch_state ->
@@ -90,7 +90,7 @@ val check_installed:
 val reinstall:
   rw switch_state -> ?assume_built:bool -> atom list -> rw switch_state
 
-(** Low-level version of [reinstall], bypassing the package name sanitization
+(** Low-level version of {!reinstall}, bypassing the package name sanitization
     and dev package update, and offering more control *)
 val reinstall_t:
   rw switch_state -> ?ask:bool -> ?force:bool -> assume_built:bool -> atom list
@@ -114,7 +114,7 @@ val upgrade:
   ?formula:formula -> ?check:bool -> ?only_installed:bool ->
   all:bool -> atom list -> rw switch_state
 
-(** Low-level version of [upgrade], bypassing the package name sanitization and
+(** Low-level version of {!upgrade}, bypassing the package name sanitization and
    dev package update, and offering more control. [terse] avoids the verbose
    message when we are at a local maximum, but there are possible upgrades *)
 val upgrade_t:

src/client/opamConfigCommand.mli

@@ -70,7 +70,7 @@ type update_op = [ append_op  | whole_op ]
     Raise [Invalid_argument] if the string is malformed *)
 val parse_update: string -> string * update_op
 
-(** As [parse_update] but parse only overwrites and reverts. String is of the
+(** As {!parse_update} but parse only overwrites and reverts. String is of the
     form [var=[value]]`.
     Raise [Invalid_argument] if the string is malformed *)
 val parse_whole: string -> string * whole_op
@@ -79,31 +79,32 @@ val whole_of_update_op: update_op -> whole_op
 
 (** [set_opt_global gt field value] updates global config field with update
     value in <opamroot>/config file. Modifiable fields are a subset of all
-    defined fields in [OpamFile.Config.t]. On revert, field is reverted to its
-    initial value as defined in [OpamInitDefaults.init_config], to default
-    value otherwise ([OpamFile.Config.empty]).
-    May raise [OpamStd.Sys.Exit 2]. *)
+    defined fields in {!OpamFile.Config.t}. On revert, field is reverted to its
+    initial value as defined in {!OpamInitDefaults.init_config}, to default
+    value otherwise ({!OpamFile.Config.empty}).
+    @raise OpamStd.Sys.Exit ([`Bad_argument], [2]) if the field is not found or not
+    modifiable, or the value have a parse error. *)
 val set_opt_global: rw global_state -> string -> update_op -> rw global_state
 
-(** As [set_opt_global], [set_opt_switch] updates switch config file in
+(** As {!set_opt_global}, {!set_opt_switch} updates switch config file in
     <opamroot>/<switch>/.opam-switch/switch-config. If switch state is given,
     uses its config and returns it with then new config. Otherwise, loads the
     raw switch state and returns [None].
-    Raises [OpamStd.Sys.Exit 50] ([`Configuration_error]) if no switch is set *)
+    @raise OpamStd.Sys.Exit ([`Configuration_error], [50]) if no switch is set *)
 val set_opt_switch:
   'a global_state -> ?st:rw switch_state -> string -> update_op
   -> rw switch_state option
 
-(** [set_var_global] and [set_var_switch] update respectively `global-variables`
+(** {!set_var_global} and {!set_var_switch} update respectively `global-variables`
     field in global config and `variables` field in switch config, by appending
     the new variables to current set. If switch state is given, uses its
     config and returns it with then new config. Otherwise, loads the raw switch
     state and returns [None].
-    Raises [OpamStd.Sys.Exit 2] ([`Bad_argument]) if field is not modifiable *)
+    @raise OpamStd.Sys.Exit ([`Bad_argument], [2]) if field is not modifiable *)
 val set_var_global:
   rw global_state -> string -> whole_op -> rw global_state
 
-(** Raises [OpamStd.Sys.Exit 50] ([`Configuration_error]) if no switch is set *)
+(** @raise OpamStd.Sys.Exit ([`Configuration_error], [50]) if no switch is set *)
 val set_var_switch:
     'a global_state -> ?st:rw switch_state -> string -> whole_op
     -> rw switch_state option
@@ -118,7 +119,7 @@ val options_list:
   ?st:unlocked switch_state -> 'a global_state -> unit
 val options_list_global: 'a global_state -> unit
 
-(** Raises [OpamStd.Sys.Exit 50] ([`Configuration_error]) if no switch is set *)
+(** @raise OpamStd.Sys.Exit ([`Configuration_error], [50]) if no switch is set *)
 val options_list_switch:
   ?st:unlocked switch_state -> 'a global_state -> unit
 
@@ -129,7 +130,7 @@ val vars_list:
   ?st:'a switch_state -> 'b global_state -> unit
 val vars_list_global: 'a global_state -> unit
 
-(** Raises [OpamStd.Sys.Exit 50] ([`Configuration_error]) if no switch is set *)
+(** @raise OpamStd.Sys.Exit ([`Configuration_error], [50]) if no switch is set *)
 val vars_list_switch:
   ?st:'a switch_state -> 'b global_state -> unit
 
@@ -142,7 +143,7 @@ val vars_list_switch:
 
 val option_show_global: 'a global_state -> string -> unit
 
-(** Raises [OpamStd.Sys.Exit 50] ([`Configuration_error]) if no switch is set *)
+(** @raise OpamStd.Sys.Exit ([`Configuration_error], [50]) if no switch is set *)
 val option_show_switch:
   'a global_state -> ?st:unlocked switch_state -> string -> unit
 

src/client/opamPinCommand.mli

@@ -15,7 +15,7 @@ open OpamTypes
 open OpamStateTypes
 
 (** Pins a package to the given version, and writes to disk. Returns the updated
-    state. The main difference with [source_pin] is that a definition overlay is
+    state. The main difference with {!source_pin} is that a definition overlay is
     not created. Therefore, the package must exist already. *)
 val version_pin: rw switch_state -> name -> version -> rw switch_state
 
@@ -31,7 +31,8 @@ exception Nothing_to_do
 
     If [force], don't abort even if the source can't be fetched from [target]
 
-    May raise [Aborted] or [Nothing_to_do]. *)
+    @raise Aborted
+    @raise Nothing_to_do *)
 val source_pin:
   rw switch_state -> name ->
   ?version:version -> ?edit:bool -> ?opam:OpamFile.OPAM.t -> ?quiet:bool ->

src/client/opamRepositoryCommand.mli

@@ -50,7 +50,7 @@ val set_url:
   rw repos_state -> repository_name -> url -> trust_anchors option ->
   rw repos_state
 
-(** Update the given repositories, as per [OpamUpdate.repositories], checks for
+(** Update the given repositories, as per {!OpamUpdate.repositories}, checks for
     their version and runs the upgrade script locally if they are for an earlier
     opam. Returns list of repositories that failed and the new repository state.
     *)

src/core/opamFilename.mli

@@ -282,20 +282,22 @@ val find_in_parents: (Dir.t -> bool) ->  Dir.t -> Dir.t option
 
 (** {2 Locking} *)
 
-(** See [OpamSystem.flock]. Prefer the higher level [with_flock] functions when
+(** See {!OpamSystem.flock}.  Prefer the higher level [with_flock] functions when
     possible *)
 val flock: [< OpamSystem.lock_flag ] -> ?dontblock:bool -> t -> OpamSystem.lock
 
 (** Calls [f] while holding a lock file. Ensures the lock is properly released
-    on [f] exit. Raises [OpamSystem.Locked] if [dontblock] is set and the lock
-    can't be acquired. [f] is passed the file_descr of the lock. *)
+    on [f] exit. [f] is passed the file_descr of the lock.
+    @raise OpamSystem.Locked if [dontblock] is set and the lock
+    can't be acquired. *)
 val with_flock: [< OpamSystem.lock_flag ] -> ?dontblock:bool -> t ->
   (Unix.file_descr -> 'a) -> 'a
 
 (** Calls [f] with the file lock upgraded to at least [flag], then restores the
     previous lock level. Upgrade to [`Lock_write] should never be used in
-    blocking mode as it would deadlock. Raises [OpamSystem.Locked] (but keeps
-    the lock as is) if [dontblock] is set and the lock can't be upgraded. *)
+    blocking mode as it would deadlock.
+    @raise OpamSystem.Locked (but keeps the lock as is) if [dontblock] is set
+    and the lock can't be upgraded. *)
 val with_flock_upgrade:
   [< OpamSystem.actual_lock_flag ] -> ?dontblock:bool -> OpamSystem.lock -> (Unix.file_descr -> 'a) -> 'a
 

src/core/opamHash.mli

@@ -41,7 +41,7 @@ val sort : t list -> t list
 
 val check_file: string -> t -> bool
 
-(** Like [check_file], but returns the actual mismatching hash of the file, or
+(** Like {!check_file}, but returns the actual mismatching hash of the file, or
     [None] in case of match *)
 val mismatch: string -> t -> t option
 

src/core/opamParallel.mli

@@ -35,8 +35,8 @@ exception Aborted
 (** Simply parallel execution of tasks *)
 
 (** In the simple iter, map and reduce cases, ints are the indexes of the jobs
-    in the list. First list is return code of sucessfull commands, second those
-    which raised expcetions, and third one those which were canceled. *)
+    in the list. First list is return code of successful commands, second those
+    which raised exceptions, and third one those which were canceled. *)
 exception Errors of int list * (int * exn) list * int list
 
 val iter: jobs:int -> command:('a -> unit OpamProcess.job) -> ?dry_run:bool ->

src/core/opamProcess.mli

@@ -98,28 +98,28 @@ type result = {
     Don't forget to call [cleanup result] afterwards *)
 val run : command -> result
 
-(** Same as [run], but doesn't wait. Use wait_one to wait and collect
+(** Same as {!run}, but doesn't wait. Use wait_one to wait and collect
     results;
     Don't forget to call [cleanup result] afterwards *)
 val run_background: command -> t
 
-(** Similar to [run_background], except that no process is created, and a dummy
+(** Similar to {!run_background}, except that no process is created, and a dummy
     process (suitable for dry_wait_one) is returned. *)
 val dry_run_background: command -> t
 
 (** [wait p] waits for the processus [p] to end and returns its results. Be
     careful to handle Sys.Break *)
 val wait: t -> result
 
-(** Like [wait], but returns None immediately if the process hasn't ended *)
+(** Like {!wait}, but returns None immediately if the process hasn't ended *)
 val dontwait: t -> result option
 
 (** Wait for the first of the listed processes to terminate, and return its
     termination status *)
 val wait_one: t list -> t * result
 
-(** Similar to [wait_one] for simulations, to be used with
-    [dry_run_background] *)
+(** Similar to {!wait_one} for simulations, to be used with
+    {!dry_run_background} *)
 val dry_wait_one: t list -> t * result
 
 (** Send SIGINT to a process (or SIGKILL on Windows) *)
@@ -205,7 +205,7 @@ module Job: sig
   val of_list: ?keep_going:bool -> command list ->
     (command * result) option Op.job
 
-  (** As [of_list], but takes a list of functions that return the commands. The
+  (** As {!of_list}, but takes a list of functions that return the commands. The
       functions will only be evaluated when the command needs to be run. *)
   val of_fun_list: ?keep_going:bool -> (unit -> command) list ->
     (command * result) option Op.job
@@ -222,7 +222,11 @@ end
 
 type 'a job = 'a Job.Op.job
 
-(**/**)
+
+(** Current environment. On Windows, Cygwin installation binary path and git
+    location path may be added to PATH. **)
+val default_env : unit -> string array
+
 (** As {!OpamStd.Sys.resolve_command}, except the default for [~env] is
     {!default_env}. *)
 val resolve_command: ?env:string array -> ?dir:string -> string -> string option
@@ -233,5 +237,3 @@ val create_process_env :
   string -> string array -> string array ->
   Unix.file_descr -> Unix.file_descr -> Unix.file_descr ->
   int
-
-val default_env : unit -> string array