Merge branch 'master' into generate-assets

Author: panglesd

CHANGES.md

@@ -6,7 +6,7 @@
   `count-occurrences` flag and command to count occurrences of every identifiers
   (@panglesd, #976)
 - Separate compilation of interface and implementation files, using a new
-  `compile-src` command (@panglesd, #1067).
+  `compile-src` command (@panglesd, #1067, #1188).
 - Add clock emoji before `@since` tag (@yawaramin, #1089)
 - Navigation for the search bar : use '/' to enter search, up and down arrows to
   select a result, and enter to follow the selected link. (@EmileTrotignon, #1088)

doc/dune.mld

@@ -32,20 +32,20 @@ Dune creates the docs for these with this command:
 $ dune build @doc
 ]}
 
-and the results will be in [_build/default/_doc/_html/].
+The results will be in [_build/default/_doc/_html/].
 
 {1:library_wrapping Dune's Library Wrapping}
 
 Dune has a feature whereby a library may be exposed under a single top-level
-module. This makes use of an OCaml feature where the use of the compiler
-flag [-no-alias-deps] is used to avoid introducing dependencies between
+module. This employs an OCaml feature where using the compiler
+flag [-no-alias-deps] will avoid introducing dependencies between
 compilation units.
 
 We aim to reduce the potential name clashes of modules by
-only exposing one main module for library users to use,
+only exposing one main module for library users,
 encapsulating all other modules as submodules, while
 still retaining the usual way of writing OCaml code with one module per
-file. These individual files are still compiled, and installed, and
+file. These individual files are still compiled, installed, and
 available in the global namespace, but their names are prefixed with
 the library's name in order to reduce the possibility of clashes. These
 prefixed modules are not intended to be used directly, so
@@ -94,22 +94,22 @@ have double underscores meaning they are hidden. Only the non-hidden module
 [Lib] is linked, and during this process, the
 the modules [A] and [B] are expanded because they are aliases of hidden
 modules. All references to [Lib__A] and [Lib__B] are replaced with the canonical
-paths [Lib.A] and [Lib.B], so in this way odoc presents the library as entirely
+paths [Lib.A] and [Lib.B], so in this way, [odoc] presents the library as entirely
 contained within the module [Lib].
 
 {2 Hand-Written Top-Level Module}
 
 In some cases it's desirable to hand-write the top-level library module. This
-is usually done because some of the modules within the library are intended to
-be internal only and not exposed. Dune will notice that a module exists with
-the name of the library ([lib.ml] in this case), so instead it will create the
-file [lib__.ml]. The contents of this are identical to the previous section, 
-with aliases for all modules. The canonical tags on the aliases are, as before,
-to [Lib.A] and [Lib.B]. These are references to module aliases that should be
-present in [lib.ml]. If these are {e not} there, [odoc] won't be able to
-resolve the canonical references, and any items from these modules that are
-exposed elsewhere will be hidden. If the items are type aliases they can be
-replaced, but otherwise they'll be rendered as unresolved links.
+is usually done because some modules in the library are intended to be internal
+only and not exposed. Dune will notice that a module exists with the library's
+name ([lib.ml] in this case), so instead it will create the file
+[lib__.ml]. Its contents are identical to the previous section, with aliases
+for all modules. Like before, the canonical tags on these aliases are
+references to [Lib.A] and [Lib.B]. These module should be present in [lib.ml]
+as module aliases. If these are {e not} there, [odoc] won't be able to resolve
+the canonical references, and any items from these modules that are exposed
+elsewhere will be hidden. If the items are type aliases, they can be replaced,
+but otherwise they'll be rendered as unresolved links.
 
 For example, consider the following module structure. First, the module [Unexposed]
 in file [unexposed.mli]:
@@ -130,10 +130,10 @@ type t = Unexposed.t
 val f : Unexposed.t
 ]}
 
-and the library module that only exposes the module [Wrapping]:
+The library module that only exposes the module [Wrapping]:
 
 {[
 module Wrapping = Wrapping
 ]}
 
-This structure is rendered {{!Odoc_examples.Wrapping}here}.
+This structure is rendered {{!Odoc_examples.Wrapping}here}.

doc/interface.mld

@@ -1,40 +1,40 @@
-{0 [odoc] interface guarantees}
+{0 [odoc] Interface Guarantees}
 
 [odoc] has several 'public facing' parts with varying levels of support guarantees.
 This document describes what those interfaces are, what the support levels are
 now, and what we aim for in the future.
 
 {2 Documentation Comments}
 
-The first and most important is the syntax of the documentation comments present in source code.
+The first and most important is the syntax of the documentation comments present in the source code.
 This is relevant to everyone who is writing code that’s intended to be documented by [odoc], so it applies to the widest set of people.
 We have a separate page describing the {{!page-ocamldoc_differences}markup differences from OCamldoc}.
 
 {2 CLI Interface}
 
-The way in which the [odoc] CLI is invoked is not trivial, and it requires careful
-ordering and correct arguments to produce correctly linked documentation. It’s not expected that
-end-users will invoke [odoc] by hand, but rather it will be driven by separate tools. As a consequence, it’s important to preserve the tools’ ability to create good documentation with
-each release of [odoc], so we’ll ensure backward compatibility of the CLI as much as possible.
+The way in which we invoke the [odoc] CLI is not trivial, and it requires careful
+ordering and accurate arguments to produce correctly linked documentation. It’s not expected that
+end users will invoke [odoc] by hand, but rather it will be driven by separate tools. As a consequence, it’s important to preserve the tools’ ability to create good documentation with
+each [odoc] release, so we’ll ensure CLI backward compatibility as much as possible.
 There are currently three ‘first class’ tools that 'drive' [odoc]. We will not make
 releases of [odoc] whilst knowingly breaking these tools. These are:
 
 - Odig
 - Dune
 - OCaml
 
-Here, OCaml refers to the newly merged configure option (from 4.12.0) that builds the standard library documentation with
-[odoc]. If the recommended way of invoking [odoc] changes, we will work with the maintainers of these projects
-to ensure they are updated correspondingly.
+Here, OCaml refers to the newly-merged configure option (from 4.12.0) that builds the standard library documentation with
+[odoc]. If the recommended way of invoking [odoc] changes, we will work with these projects' maintainers
+to ensure they are updated accordingly.
 
 Additionally, there will be a reference implementation of a tool to build [odoc]'s documentation, which should
 serve as a guide for anyone building other 'drivers' of [odoc].
 
 {2 Output Formats}
 
 [odoc] currently outputs HTML files, man pages, and LaTex documents. In a similar vein to the CLI interface,
-we will try to ensure that the three tools described above will  not be broken by any changes to the
-outputs. That is, they will succeed and produce ‘correct’ documentation. Although, we don’t make any
+we will try to ensure that any changes to the outputs will not break the three tools described above. 
+That is, they will succeed and produce ‘correct’ documentation. However, we don’t make any
 guarantees about the internal structure of the output documents; e.g., the exact nesting of
 tags or sequence of LaTex commands may not be preserved. We will attempt to ensure that the HTML anchors are preserved, implying that the filenames will also be preserved.
 
@@ -45,5 +45,5 @@ no guarantees about the stability of the API.
 
 {2 Intermediate Files}
 
-The intermediate files that [odoc] produces ([.odoc] and [.odocl]) should be considered to be internal only
+The intermediate files that [odoc] produces ([.odoc] and [.odocl]) should be considered internal only
 and tied to the specific version of [odoc].