Make docstring indentation consistent + some docs rewording (#159)

src-cmd/dockerfile_cmd.mli

@@ -40,7 +40,7 @@ val run_log :
   Bos.Cmd.t ->
   (unit, [> `Msg of string ]) result
 (** [runlog log_dir name cmd] will run [cmd] with label [name]
-   and log the results in [<log_dir>/<name>.sxp]. *)
+    and log the results in [<log_dir>/<name>.sxp]. *)
 
 (** Docker command invocation *)
 module Docker : sig

src-opam/distro.mli

@@ -146,7 +146,7 @@ type distro =
   | `Cygwin of win10_release
   | `Windows of [ `Mingw | `Msvc ] * win10_release ]
 [@@deriving sexp]
-(** Supported Docker container distributions distributions. *)
+(** Supported Docker container distributions without aliases. *)
 
 type t =
   [ `Alpine of
@@ -223,7 +223,7 @@ type t =
   | `Cygwin of win_all
   | `Windows of [ `Mingw | `Msvc ] * win_all ]
 [@@deriving sexp]
-(** Supported Docker container distributions. *)
+(** Supported Docker container distributions with aliases such as [`Latest]. *)
 
 type os_family = [ `Cygwin | `Linux | `Windows ] [@@deriving sexp]
 (** The operating system family a distro belongs to. *)
@@ -237,22 +237,22 @@ val os_family_to_string : os_family -> string
 
 val opam_repository : os_family -> string
 (** [opam_repository os_family] returns the git URL to the default
-   Opam repository. *)
+    Opam repository. *)
 
 val personality : os_family -> Ocaml_version.arch -> string option
 (** [personality os_family arch] returns the personality associated to
-   the architecture, if [os_family] is [`Linux]. *)
+    the architecture, if [os_family] is [`Linux]. *)
 
 val is_same_distro : t -> t -> bool
 (** [is_same_distro d1 d2] returns whether [d1] is the same distro as
-   [d2], regardless of their respective versions. *)
+    [d2], regardless of their respective versions. *)
 
 val compare : t -> t -> int
 (** [compare a b] is a lexical comparison function for {!t}. *)
 
 val resolve_alias : t -> distro
 (** [resolve_alias t] will resolve [t] into a concrete version. This removes
-   versions such as [Latest]. *)
+    versions such as [Latest]. *)
 
 val distros : t list
 (** Enumeration of the supported Docker container distributions. *)
@@ -265,25 +265,25 @@ val win10_latest_release : win10_release
 
 val win10_latest_image : win10_release
 (** Latest Windows 10 Docker image available. May differ from
-   {!win10_latest_release} if the Docker repository hasn't been
-   updated. *)
+    {!win10_latest_release} if the Docker repository hasn't been
+    updated. *)
 
 val master_distro : t
 (** The distribution that is the top-level alias for the [latest] tag
     in the [ocaml/opam2] Docker Hub build. *)
 
 val builtin_ocaml_of_distro : t -> string option
 (** [builtin_ocaml_of_distro t] will return the OCaml version
-  supplied with the distribution packaging, and [None] if there
-  is no supported version. *)
+    supplied with the distribution packaging, and [None] if there
+    is no supported version. *)
 
 val human_readable_string_of_distro : t -> string
 (** [human_readable_string_of_distro t] returns a human readable
-  version of the distribution tag, including version information. *)
+    version of the distribution tag, including version information. *)
 
 val human_readable_short_string_of_distro : t -> string
 (** [human_readable_short_string_of_distro t] returns a human readable
-  short version of the distribution tag, excluding version information. *)
+    short version of the distribution tag, excluding version information. *)
 
 type package_manager =
   [ `Apk  (** Alpine Apk *)
@@ -297,13 +297,13 @@ type package_manager =
 (** The package manager used by a distro. *)
 
 val package_manager : t -> package_manager
-(** [package_manager t] returns the type of package manager used
- by that distribution.  Many derived distributions (such as OracleLinux)
- share the same package manager from a base distribution (such as CentOS). *)
+(** [package_manager t] returns the package manager used by that distribution.
+    Many derived distributions (such as OracleLinux) share the same package
+    manager from a base distribution (such as CentOS). *)
 
 val bubblewrap_version : t -> (int * int * int) option
 (** [bubblewrap_version t] returns the version of bubblewrap available on that
- distribution. *)
+    distribution. *)
 
 (** {2 Docker Hub addresses} *)
 
@@ -316,10 +316,10 @@ val distro_of_tag : string -> t option
 
 val latest_tag_of_distro : t -> string
 (** [latest_tag_of_distro distro] will generate a Docker Hub
-  tag that is a convenient short form for the latest stable
-  release of a particular distribution.  This tag will be
-  regularly rewritten to point to any new releases of the
-  distribution. *)
+    tag that is a convenient short form for the latest stable
+    release of a particular distribution.  This tag will be
+    regularly rewritten to point to any new releases of the
+    distribution. *)
 
 type win10_docker_base_image =
   [ `NanoServer  (** Windows Nano Server *)
@@ -334,28 +334,28 @@ val win10_base_tag :
   win_all ->
   string * string
 (** [win10_base_tag base_image release] will return a tuple of Windows
-   container base image and tag for which the base image of a Windows
-   base image can be found (e.g.
-   [mcr.microsoft.com/windows/servercore],[ltsc2022] which maps to
-   [mcr.microsoft.com/windows/servercore:ltsc2022] on the Microsoft
-   Container Registry). *)
+    container base image and tag for which the base image of a Windows
+    base image can be found (e.g.
+    [mcr.microsoft.com/windows/servercore],[ltsc2022] which maps to
+    [mcr.microsoft.com/windows/servercore:ltsc2022] on the Microsoft
+    Container Registry). *)
 
 val base_distro_tag :
   ?win10_revision:win10_lcu -> ?arch:Ocaml_version.arch -> t -> string * string
 (** [base_distro_tag ?arch t] will return a tuple of a Docker Hub
- user/repository and tag for which the base image of a distribution
- can be found (e.g. [opensuse/leap],[15.0] which maps to [opensuse/leap:15.0]
- on the Docker Hub).  This base image is in turn can be used to generate opam
- and other OCaml tool Dockerfiles. [arch] defaults to [x86_64] and can vary
- the base user/repository since some architecture are built elsewhere. *)
+    user/repository and tag for which the base image of a distribution
+    can be found (e.g. [opensuse/leap],[15.0] which maps to [opensuse/leap:15.0]
+    on the Docker Hub).  This base image is in turn can be used to generate opam
+    and other OCaml tool Dockerfiles. [arch] defaults to [x86_64] and can vary
+    the base user/repository since some architecture are built elsewhere. *)
 
 val win10_release_to_string : win10_release -> string
 (** [win10_release_to_string update] converts a Windows 10 version name to
-   string. *)
+    string. *)
 
 val win10_release_of_string : string -> win_all option
 (** [win10_release_of_string] converts a Windows 10 version name as
-   string to its internal representation. Ignores any KB number. *)
+    string to its internal representation. Ignores any KB number. *)
 
 val win10_revision_to_string : win10_revision -> string
 val win10_revision_of_string : string -> win10_revision option
@@ -378,8 +378,8 @@ type win10_release_status = [ `Deprecated | `Active ]
 
 val win10_release_status : win_all -> win10_release_status
 (** [win10_release_status v channel] returns the Microsoft support
-   status of the specified Windows 10 release.
-   @see <https://en.wikipedia.org/wiki/Windows_10_version_history#Channels> *)
+    status of the specified Windows 10 release.
+    @see <https://en.wikipedia.org/wiki/Windows_10_version_history#Channels> *)
 
 val active_distros : Ocaml_version.arch -> t list
 (** [active_distros arch] returns the list of currently supported

src-opam/opam.mli

@@ -56,17 +56,17 @@ val gen_opam2_distro :
   Distro.t ->
   string * Dockerfile.t
 (** [gen_opam2_distro ~opam_hashes d] will generate a Dockerfile
-   for Linux distribution [d] with opam 2.0, opam 2.1, opam 2.2 and opam master,
-   per hash given in parameter.
-   @return a tuple of the Docker tag and the Dockerfile.
-   If [clone_opam_repo] is true (the default) then the Dockerfile will also git
-   clone the official opam-repository into [/home/opam/opam-repository].
-   If [arch] is not specified, it defaults to the base image that is assumed
-   to be multiarch (the main exception to this is i386, which requires different
-   base images from amd64).
-   For native Windows distributions, if [winget] is omitted, then winget
-   will be build in an prepended build stage. If specified, then
-   winget will be pulled from the [winget] external image. *)
+    for Linux distribution [d] with opam 2.0, opam 2.1, opam 2.2 and opam master,
+    per hash given in parameter.
+    @return a tuple of the Docker tag and the Dockerfile.
+    If [clone_opam_repo] is true (the default) then the Dockerfile will also git
+    clone the official opam-repository into [/home/opam/opam-repository].
+    If [arch] is not specified, it defaults to the base image that is assumed
+    to be multiarch (the main exception to this is i386, which requires different
+    base images from amd64).
+    For native Windows distributions, if [winget] is omitted, then winget
+    will be build in an prepended build stage. If specified, then
+    winget will be pulled from the [winget] external image. *)
 
 val ocaml_depexts : Distro.t -> Ocaml_version.t -> Dockerfile.t
 (** [ocaml_depexts distro version] returns packages that are
@@ -76,21 +76,21 @@ val ocaml_depexts : Distro.t -> Ocaml_version.t -> Dockerfile.t
 val all_ocaml_compilers :
   string -> Ocaml_version.arch -> Distro.t -> string * Dockerfile.t
 (** [all_ocaml_compilers hub_id arch distro] will generate an opam2
-  container that has all the recent OCaml compilers installed into a
-  distribution [distro] on architecture [arch]. *)
+    container that has all the recent OCaml compilers installed into a
+    distribution [distro] on architecture [arch]. *)
 
 val separate_ocaml_compilers :
   string -> Ocaml_version.arch -> Distro.t -> (string * Dockerfile.t) list
 (** [separate_ocaml_compilers hub_id arch distro] will install a list of
-  Dockerfiles that build individual OCaml compiler versions and their
-  variants (e.g. flambda) in separate containers. *)
+    Dockerfiles that build individual OCaml compiler versions and their
+    variants (e.g. flambda) in separate containers. *)
 
 val deprecated : Dockerfile.t
 (** [deprecated] is a minimal container that outputs a deprecation error. This
-   is used to replace unsupported containers on the Hub rather than leaving an
-   unmaintained distribution lying around with possible security holes. *)
+    is used to replace unsupported containers on the Hub rather than leaving an
+    unmaintained distribution lying around with possible security holes. *)
 
 val multiarch_manifest :
   target:string -> platforms:(string * string) list -> string
 (** [multiarch_manifest ~target ~platforms] will generate a manifest-tool compliant yaml file to
-  build a [target] on the given multiarch [platforms]. *)
+    build a [target] on the given multiarch [platforms]. *)

src-opam/windows.mli

@@ -26,18 +26,18 @@ val run_powershell :
   ?escape:(string -> string) -> ('a, unit, string, t) format4 -> 'a
 (** [run_powershell fmt] will execute [powershell -Command "fmt"].
 
-    @param escape (defaults to {!Fun.id}) allows to escape [fmt]
-      because the calling shell (usually [cmd]) might interpret
-      unwanted things in [fmt]. This might help embedding readable
-      powershell code. *)
+      @param escape (defaults to {!Fun.id}) allows to escape [fmt]
+        because the calling shell (usually [cmd]) might interpret
+        unwanted things in [fmt]. This might help embedding readable
+        powershell code. *)
 
 val run_vc : arch:Ocaml_version.arch -> ('a, unit, string, t) format4 -> 'a
 (** [run_vc ~arch fmt] will execute [run fmt] with Visual
-   Compiler for [~arch] loaded in the environment. *)
+    Compiler for [~arch] loaded in the environment. *)
 
 val run_ocaml_env : string list -> ('a, unit, string, t) format4 -> 'a
 (** [run_ocaml_env args fmt] will execute [fmt] in the environment
-   loaded by [ocaml-env exec] with [args]. *)
+    loaded by [ocaml-env exec] with [args]. *)
 
 val sanitize_reg_path : unit -> t
   [@@ocaml.doc
@@ -53,20 +53,20 @@ val sanitize_reg_path : unit -> t
 
 val install_vc_redist : ?vs_version:string -> unit -> t
 (** Install Microsoft Visual C++ Redistributable.
-   @see <https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads> *)
+    @see <https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads> *)
 
 val install_visual_studio_build_tools : ?vs_version:string -> string list -> t
 (** Install Visual Studio Build Tools components.
-   @see <https://docs.microsoft.com/en-us/visualstudio/install/workload-component-id-vs-build-tools?view=vs-2019> *)
+    @see <https://docs.microsoft.com/en-us/visualstudio/install/workload-component-id-vs-build-tools?view=vs-2019> *)
 
 val ocaml_for_windows_package_exn :
   switch:Ocaml_version.t ->
   port:[ `Mingw | `Msvc ] ->
   arch:Ocaml_version.arch ->
   string * string
 (** [ocaml_for_windows_variant ~port ~arch] returns the
-   [(package_name, package_version)] of the OCaml compiler
-   package in OCaml for Windows, if applicable. *)
+    [(package_name, package_version)] of the OCaml compiler
+    package in OCaml for Windows, if applicable. *)
 
 val remove_system_attribute : ?recurse:bool -> string -> t
 (** Remove the system attribute on a path. Might be useful to copy
@@ -86,34 +86,33 @@ module Cygwin : sig
     root : string;  (** Root installation directory *)
     site : string;  (** Download site URL *)
     args : string list;
-        (** List of arguments to give to Cygwin's setup, except
-           [--root] and [--site]. *)
   }
+  (** List of arguments to give to Cygwin's setup, except [--root] and [--site]. *)
 
   val default : cyg
   (** The default Cygwin root, mirror, and arguments. *)
 
   val install_from_release :
     ?cyg:cyg -> ?msvs_tools:bool -> ?extra:string list -> unit -> Dockerfile.t
-  (** Install Cygwin with CygSymPathy and optionally msvs-tools, and [extra] Cygwin
-     packages (first in a separate Docker image). Sets the
-     [CYGWIN=winsymlinks:native] environment variable.
-     @see <https://github.com/metastack/cygsympathy>
-     @see <https://github.com/metastack/msvs-tools> *)
+  (** Install Cygwin with CygSymPathy and optionally msvs-tools,
+      and [extra] Cygwin packages (first in a separate Docker image).
+      Sets the [CYGWIN=winsymlinks:native] environment variable.
+      @see <https://github.com/metastack/cygsympathy>
+      @see <https://github.com/metastack/msvs-tools> *)
 
   val setup : ?cyg:cyg -> ?from:string -> unit -> t
   (** Setup winget, optionally copied from the [from] Docker image.  *)
 
   val install : ?cyg:cyg -> string list -> Dockerfile.t
   (** Install the supplied Cygwin package list. The packages should be
-     comma-separated. *)
+      comma-separated. *)
 
   val update : ?cyg:cyg -> unit -> t
   (** Update Cygwin packages. *)
 
   val cygwin_packages : ?flexdll_version:string -> unit -> string list
   (** [cygwin_packages ?extra ()] is the list of the base development
-     tools for the OCaml Cygwin port. *)
+      tools for the OCaml Cygwin port. *)
 
   val mingw_packages : string list
   (** [mingw_packages] is the list of base development tools for the
@@ -126,18 +125,18 @@ module Cygwin : sig
   val ocaml_for_windows_packages :
     ?cyg:cyg -> ?extra:string list -> ?version:string -> unit -> string list * t
   (** [ocaml_for_windows_packages ?extra ()] returns the list of
-     Cygwin packages dependencies, and the installation instructions.
-     Extra packages may also be optionally supplied via [extra].
-     @see <https://fdopen.github.io/opam-repository-mingw/> *)
+      Cygwin packages dependencies, and the installation instructions.
+      Extra packages may also be optionally supplied via [extra].
+      @see <https://fdopen.github.io/opam-repository-mingw/> *)
 
   val run_sh : ?cyg:cyg -> ('a, unit, string, t) format4 -> 'a
   (** [run_sh ?cyg fmt] will execute in the Cygwin root
-     [\bin\bash.exe --login -c "fmt"]. *)
+      [\bin\bash.exe --login -c "fmt"]. *)
 
   val run_sh_ocaml_env :
     ?cyg:cyg -> string list -> ('a, unit, string, t) format4 -> 'a
   (** [run_cmd_ocaml_env args fmt] will execute [fmt] in the environment
-     loaded by [ocaml-env cygwin exec] with [args]. *)
+      loaded by [ocaml-env cygwin exec] with [args]. *)
 
   (** Rules for Git. *)
   module Git : sig
@@ -150,9 +149,9 @@ module Cygwin : sig
       t
     (** Configure the git name and email variables to sensible defaults.
 
-       @param repos A list of paths to Git repos to mark as safe
-         directories. Defaults to the default location of the
-         opam-repository. *)
+        @param repos A list of paths to Git repos to mark as safe
+          directories. Defaults to the default location of the
+          opam-repository. *)
   end
 end
 
@@ -161,12 +160,12 @@ end
 module Winget : sig
   val is_supported : Distro.win_all -> bool
   (** Winget 1.0.11692 discontinued support for versions older than
-     Windows 10 1809. Older versions of Winget have bugs, don't use
-     them. *)
+      Windows 10 1809. Older versions of Winget have bugs, don't use
+      them. *)
 
   val install_from_release : ?winget_version:string -> unit -> t
   (** Install winget from a released build (first in a separate Docker
-     image). The optional [winget_version] specifies a Git tag. *)
+      image). The optional [winget_version] specifies a Git tag. *)
 
   val setup : ?from:string -> unit -> t
   (** Setup winget, optionally copied from the [from] Docker
@@ -185,8 +184,8 @@ module Winget : sig
     val init : ?name:string -> ?email:string -> ?repos:string list -> unit -> t
     (** Configure the git name and email variables to sensible defaults.
 
-       @param repos A list of paths to Git repos to mark as safe
-         directories. Defaults to the default location of the
-         opam-repository. *)
+        @param repos A list of paths to Git repos to mark as safe
+          directories. Defaults to the default location of the
+          opam-repository. *)
   end
 end