Fix most doc errors

build_system/ninja_utils.mli

@@ -14,14 +14,16 @@
    License for the specific language governing permissions and limitations under
    the License. *)
 
-(** {2 What (** This library contains the implementations of utility functions
+(** This library contains the implementations of utility functions used to
-    used to generate {{:https://ninja-build.org} Ninja} build files in OCaml
+    generate {{:https://ninja-build.org} Ninja} build files in OCaml with almost
-    with almost no dependencies -- it only depends on
+    no dependencies -- it only depends on
     {{:https://v3.ocaml.org/p/re/1.10.3/doc/Re/index.html} Re}. It's currently
     developed to be used by
     {{:https://github.com/CatalaLang/catala/tree/master/build_system} Clerk},
     the {{:https://catala-lang.org} Catala} build system. Therefore, the library
-    {b supports only very basic features} required by Clerk. *) is Ninja?} *)
+    {b supports only very basic features} required by Clerk. *)
+
+(** {2 What is Ninja?} *)
 
 (** {{:https://ninja-build.org} Ninja} is a low-level build system. It's
     designed to have its input files ({i build.ninja}) generated by a
@@ -74,8 +76,8 @@ module Rule : sig
       ]} *)
 
   val make : string -> command:Expr.t -> description:Expr.t -> t
-  (** [make name ~command ~description] returns the corresponding ninja {!type:
+  (** [make name ~command ~description] returns the corresponding ninja
-      Rule.t}. *)
+      {!type:Rule.t}. *)
 
   val format : Format.formatter -> t -> unit
   (** [format fmt rule] outputs in [fmt] the string representation of the ninja
@@ -101,18 +103,18 @@ module Build : sig
       ]}*)
 
   val make : outputs:Expr.t list -> rule:string -> t
-  (** [make ~outputs ~rule] returns the corresponding ninja {!type: Build.t}
+  (** [make ~outputs ~rule] returns the corresponding ninja {!type:Build.t} with
-      with no {!field: inputs} or {!field: vars}. *)
+      no {!field:inputs} or {!field:vars}. *)
 
   val make_with_vars :
     outputs:Expr.t list -> rule:string -> vars:(string * Expr.t) list -> t
   (** [make_with_vars ~outputs ~rule ~vars] returns the corresponding ninja
-      {!type: Build.t} with no {!field: inputs}. *)
+      {!type:Build.t} with no {!field:inputs}. *)
 
   val make_with_inputs :
     outputs:Expr.t list -> rule:string -> inputs:Expr.t list -> t
   (** [make_with_vars ~outputs ~rule ~inputs] returns the corresponding ninja
-      {!type: Build.t} with no {!field: vars}. *)
+      {!type:Build.t} with no {!field:vars}. *)
 
   val make_with_vars_and_inputs :
     outputs:Expr.t list ->
@@ -124,8 +126,8 @@ module Build : sig
       ninja {!type: Build.t}. *)
 
   val empty : t
-  (** [empty] is the minimal ninja {!type: Build.t} with ["empty"] as {!field:
+  (** [empty] is the minimal ninja {!type:Build.t} with ["empty"] as
-      outputs} and ["phony"] as {!field: rule}. *)
+      {!field:outputs} and ["phony"] as {!field: rule}. *)
 
   val unpath : ?sep:string -> string -> string
   (** [unpath ~sep path] replaces all [/] occurences with [sep] in [path] to

compiler/catala_utils/catala_utils.mld

@@ -7,12 +7,12 @@ In {{: desugared.html} the desugared representation} or in the
 global identifiers. These identifiers use OCaml's type system to statically
 distinguish e.g. a scope identifier from a struct identifier.
 
-The {!module: Uid} module provides a generative functor whose output is
+The {!module:Catala_utils.Uid} module provides a generative functor whose output is
 a fresh sort of global identifiers.
 
 Related modules:
 
-{!modules: Uid}
+{!modules: Catala_utils.Uid}
 
 {1 Source code positions}
 
@@ -22,7 +22,7 @@ code. These annotations are critical to produce readable error messages.
 
 Related modules:
 
-{!modules: Pos}
+{!modules: Catala_utils.Pos}
 
 {1 Error messages}
 
@@ -31,14 +31,14 @@ of error messages inspired by the Rust compiler, where error messages all
 correspond to the same exception. This exception carries messages and positions
 that are displayed in the end in a nicely-formatted error message.
 
-Hence, all error thrown by the compiler should use {!module: Utils.Errors}
+Hence, all error thrown by the compiler should use {!module:Catala_utils.Messages}
 
 Related modules:
 
-{!modules: Utils.Errors}
+{!modules: Catala_utils.Messages}
 
 {1 Other utilies}
 
 Related modules:
 
-{!modules: Utils.File Utils.String_common}
+{!modules: Catala_utils.File Catala_utils.Mark Catala_utils.Cli Catala_utils.String}

compiler/catala_utils/pos.mli

@@ -33,7 +33,11 @@ val get_end_column : t -> int
 val get_file : t -> string
 
 val join : t -> t -> t
-(** Returns the smallest range including both supplied ranges. @raise Invalid_argument if they don't belong to the same file. The law position used is the one of the earliest position. *)
+(** Returns the smallest range including both supplied ranges.
+
+    @raise Invalid_argument
+      if they don't belong to the same file. The law position used is the one of
+      the earliest position. *)
 
 type input_file = FileName of string | Contents of string
 

compiler/dcalc/dcalc.mld

@@ -8,7 +8,6 @@ lowered to sum and product types. The default calculus can be later compiled
 to a {{: lcalc.html} lambda calculus}.
 
 The module describing the abstract syntax tree is {!module: Dcalc.Ast}.
-Printing helpers can be found in {!module: Dcalc.Print}.
 This intermediate representation corresponds to the default calculus
 presented in the {{: https://arxiv.org/abs/2103.03198} Catala formalization}.
 
@@ -16,34 +15,13 @@ Related modules:
 
 {!modules: Dcalc.Ast}
 
-{1 Typing }
+{ 1 Invariants }
 
-This representation is where the typing is performed. Indeed, {!module: Dcalc.Typing}
+While Dcalc is a superset of a fully-fledged simply typed lambda calculus,
-implements the classical {{: https://en.wikipedia.org/wiki/Hindley%E2%80%93Milner_type_system} W algorithm}
+the Dcalc code actually generated from the previous intermediate representation
-corresponding to a Hindley-Milner type system, without type constraints.
+obeys some strict structural invariants. Those are formalized and empirically
+tested in {!module:Dcalc.Invariants}.
 
 Related modules:
 
-{!modules: Dcalc.Typing}
+{!modules: Dcalc.Invariants}
-
-{1 Interpreter}
-
-Since this representation is currently the last of the compilation chain,
-an {!module: Dcalc.Interpreter} module is provided to match the execution
-semantics of the default calculus.
-
-Later, translations to a regular lambda calculus and/or a simple imperative
-language are bound to be added.
-
-Related modules:
-
-{!modules: Dcalc.Interpreter}
-
-{1 Optimizations}
-
-Classical optimizations passes can be performed on the Dcalc AST: partial
-evaluation, beta and iota-reduction, etc.
-
-Related modules:
-
-{!modules: Dcalc.Optimizations}

compiler/desugared/desugared.mld

@@ -16,15 +16,15 @@ Before the translation to the {{: scopelang.html} scope language},
 {!module: Desugared.Dependency} checks that within
 a scope, there is no computational circular dependency between the variables
 of the scope. When the dependency graph is a DAG,
-{!module: Desugared.Desugared_to_scope} performs a topological ordering to
+{!module:Scopelang.From_desugared} performs a topological ordering to
 produce an ordered list of the scope definitions compatible with the
 computation order. All the graph computations are done using the
 {{:http://ocamlgraph.lri.fr/} Ocamlgraph} library.
 
 The other important piece of work performed by
-{!module: Desugared.Desugared_to_scope} is the construction of the default trees
+{!module:Scopelang.From_desugared} is the construction of the default trees
 (see {!Shared_ast.EDefault}) from the list of prioritized rules.
 
 Related modules:
 
-{!modules: Desugared.Dependency Desugared.Desugared_to_scope}
+{!modules: Desugared.Dependency Scopelang.From_desugared}

compiler/desugared/name_resolution.mli

@@ -88,7 +88,7 @@ type context = {
   var_typs : var_sig ScopeVar.Map.t;
       (** The signatures of each scope variable declared *)
 }
-(** Main context used throughout {!module: Surface.Desugaring} *)
+(** Main context used throughout {!module: Desugared.From_surface} *)
 
 (** {1 Helpers} *)
 

compiler/index.mld

@@ -88,6 +88,7 @@ More documentation can be found on each intermediate representations here.
 {li {{: scalc.html} The statement calculus}}
 }
 
+Most of these intermediate representations use a {{: shared_ast.html} shared AST libary}.
 The main compilation chain is defined in:
 
 {!modules: Driver}
@@ -113,7 +114,7 @@ The Catala runtimes documentation is available here:
 Last, it is possible to customize the backend to the compiler using a plugin
 mechanism. The API is defined inside the following module:
 
-{!modules: Driver.Plugin}
+{!module: Driver.Plugin}
 
 See the examples in the [plugins/] subdirectory:
 

compiler/lcalc/lcalc.mld

@@ -2,12 +2,12 @@
 
 This representation is the fifth in the compilation chain
 (see {{: index.html#architecture} Architecture}). Its main difference
-with the previous {{: Dcalc.html} default calculus} is the absence of the
+with the previous {{: dcalc.html} default calculus} is the absence of the
 default term, which has been eliminated through diverse compilation schemes.
 
 The module describing the abstract syntax tree is:
 
-{!modules: Lcalc.Ast Lcalc.Print}
+{!modules: Lcalc.Ast}
 
 This intermediate representation corresponds to the lambda calculus
 presented in the {{: https://arxiv.org/abs/2103.03198} Catala formalization}.
@@ -16,11 +16,12 @@ presented in the {{: https://arxiv.org/abs/2103.03198} Catala formalization}.
 
 {!module: Lcalc.Compile_with_exceptions} compiles the default term of the
 default calculus using catchable exceptions. This compilation scheme has been
-certified.
+certified. Another compilation scheme that uses an option monad instead is
+available at {!module:Lcalc.Compile_without_exceptions}.
 
 Related modules:
 
-{!modules: Lcalc.Compile_with_exceptions}
+{!modules: Lcalc.Compile_with_exceptions Lcalc.Compile_without_exceptions}
 
 {1 Backends}
 
@@ -29,5 +30,5 @@ since the core of the OCaml value language is effectively a lambda calculus.
 
 Related modules:
 
-{!modules: Lcalc.To_ocaml Scalc.To_python Lcalc.Backends}
+{!modules: Lcalc.To_ocaml}
 

compiler/literate/literate_common.mli

@@ -17,27 +17,29 @@
 open Catala_utils
 
 val literal_title : Cli.backend_lang -> string
-(** Return the title traduction according the given {!type:Cli.backend_lang}. *)
+(** Return the title traduction according the given
+    {!type:Catala_utils.Cli.backend_lang}. *)
 
 val literal_generated_by : Cli.backend_lang -> string
 (** Return the 'generated by' traduction according the given
-    {!type:Cli.backend_lang}. *)
+    {!type:Catala_utils.Cli.backend_lang}. *)
 
 val literal_source_files : Cli.backend_lang -> string
 (** Return the 'source files weaved' traduction according the given
-    {!type:Cli.backend_lang}. *)
+    {!type:Catala_utils.Cli.backend_lang}. *)
 
 val literal_disclaimer_and_link : Cli.backend_lang -> string
 (** Return the traduction of a paragraph giving a basic disclaimer about Catala
-    and a link to the website according the given {!type: Cli.backend_lang}. *)
+    and a link to the website according the given
+    {!type:Catala_utils.Cli.backend_lang}. *)
 
 val literal_last_modification : Cli.backend_lang -> string
 (** Return the 'last modification' traduction according the given
-    {!type:Cli.backend_lang}. *)
+    {!type:Catala_utils.Cli.backend_lang}. *)
 
 val get_language_extension : Cli.backend_lang -> string
 (** Return the file extension corresponding to the given
-    {!type:Cli.backend_lang}. *)
+    {!type:Catala_utils.Cli.backend_lang}. *)
 
 val run_pandoc : string -> [ `Html | `Latex ] -> string
 (** Runs the [pandoc] on a string to pretty-print markdown features into the

compiler/plugin.mli

@@ -68,6 +68,4 @@ module PluginAPI : sig
     unit
 end
 
-(**/*)
-
 val register : t -> unit

compiler/scalc/scalc.mld

@@ -12,13 +12,13 @@ The module describing the abstract syntax tree is:
 
 {1 Compilation from lambda calculus }
 
-{!module: Scalc.From_lambda} Performs the classical translation
+{!module: Scalc.From_lcalc} Performs the classical translation
 from an expression-based language to a statement-based language. Union types
 are eliminated in favor of tagged unions.
 
 Related modules:
 
-{!modules: Scalc.From_lambda}
+{!modules: Scalc.From_lcalc}
 
 {1 Backends}
 

compiler/scopelang/scopelang.mld

@@ -4,7 +4,7 @@ This representation is the third in the compilation chain
 (see {{: index.html#architecture} Architecture}). Its main difference
 with the previous {{: desugared.html} desugared representation} is that inside
 a scope, the definitions are ordered according to their computational
-dependency order, and each definition is a {!Dcalc.Ast.EDefault} tree
+dependency order, and each definition is a {!Shared_ast.EDefault} tree
 instead of a flat list of rules.
 
 The module describing the abstract syntax tree is:
@@ -29,11 +29,11 @@ The translation from the scope language to the
 }
 
 1 and 3 involve computing dependency graphs for respectively the structs and
-enums on one hand, and the inter-scope dependencies on the other hand. Both
+enums on one hand, and the inter-scope dependencies on the other hand. Both can
-can be found in {!module: Scopelang.Dependency}, while
+be found in {!module:Scopelang.Dependency}, while {!module:Dcalc.From_scopelang}
-{!module: Scopelang.Scope_to_dcalc} is mostly responsible for 2.
+is mostly responsible for 2.
 
 
 Related modules:
 
-{!modules: Scopelang.Dependency Scopelang.Scope_to_dcalc}
+{!modules: Scopelang.Dependency Dcalc.From_scopelang}

compiler/shared_ast/dune

@@ -4,3 +4,7 @@
  (flags
   (:standard -short-paths))
  (libraries bindlib unionFind catala_utils catala.runtime_ocaml alcotest))
+
+(documentation
+ (package catala)
+ (mld_files shared_ast))

compiler/shared_ast/operator.mli

@@ -21,13 +21,14 @@
     - During desugaring, the operators may remain untyped (with [TAny]) or, if
       they have an explicit type suffix (e.g. the [$] for "money" in [+$]),
       their operands types are already explicited in the [EOp] expression node.
-    - {!modules:Shared_ast.Typing} will then enforce these constraints in
+
+    - {!module:Shared_ast.Typing} will then enforce these constraints in
       addition to the known built-in type for each operator (e.g.
       [Eq: 'a -> 'a -> 'a] isn't encoded in the first-order AST types).
-    - Finally, during {!modules:Scopelang.From_desugared}, these types are
+
+    - Finally, during {!module:Scopelang.From_desugared}, these types are
       leveraged to resolve the overloaded operators to their concrete,
-      monomorphic counterparts
+      monomorphic counterparts *)
-*)
 
 open Catala_utils
 open Definitions

compiler/shared_ast/shared_ast.mld

@@ -3,14 +3,13 @@
 This module contains a generic AST structure, various type definitions and
 helpers that are reused in various passes of the compiler.
 
-{1 The {!modules: Shared_ast.Definitions} module}
+{1 The [Shared_ast.Definitions] module}
 
-The main module {!modules: Shared_ast.Definitions} is exposed at top-level of
+The main module {!module: Shared_ast} is exposed at top-level of
 the library (so that [open Shared_ast] gives access to the structures). It
-defines literals, operators, and in particular the type {!types:
+defines literals, operators, and in particular the type {!type:Shared_ast.naked_gexpr}.
-Shared_ast.naked_gexpr}.
 
-The {!types: Shared_ast.naked_gexpr} type regroups all the cases for the {{:
+The {!type:Shared_ast.naked_gexpr} type regroups all the cases for the {{:
 ../dcalc.html} Dcalc} and {{: ../lcalc.html} Lcalc} ASTs, with unconstrained
 annotations (used for positions, types, etc.). A GADT is used to eliminate
 irrelevant cases, so that e.g. [(dcalc, _) naked_gexpr] doesn't have the [ERaise] and
@@ -28,13 +27,17 @@ structures that are also shared between different compiler passes.
 
 {1 Helper library}
 
-The {!modules: Shared_ast.Var} defines ['e Var.Set.t] and [('e, _) Var.Map.t]
+The {!module: Shared_ast.Var} defines ['e Var.Set.t] and [('e, _) Var.Map.t]
 types that are useful to handle variables for the different ['e] expression
 types without re-instanciating [Set.Make] and [Map.Make] each time.
 
-{!modules: Shared_ast.Expr} contains various helpers to build well-formed
+{!module: Shared_ast.Expr} contains various helpers to build well-formed
 expressions, and for traversal.
 
-{!modules: Shared_ast.Scope Shared_ast.Program} are dedicated to handling the
+The following modules are dedicated to handling the program structure around
-program structure around expressions. Note that these don't make sense for the
+expressions. Note that these don't make sense for the early compiler passes (up
-early compiler passes (up to [Scopelang]).
+to [Scopelang]).
+
+
+{!modules: Shared_ast.Scope Shared_ast.Program}
+

compiler/surface/surface.mld

@@ -67,12 +67,12 @@ Relevant modules:
 The desugaring consists of translating {!module: Surface.Ast} to
 {!module: Desugared.Ast} of the {{: desugared.html} desugared representation}.
 The translation is implemented in
-{!module: Surface.Desugaring}, but it relies on a helper module to perform the
+{!module:Desugared.From_surface}, but it relies on a helper module to perform the
-name resolution: {!module: Surface.Name_resolution}. Indeed, in
+name resolution: {!module:Desugared.Name_resolution}. Indeed, in
 {!module: Surface.Ast}, the variables identifiers are just [string], whereas in
 {!module: Desugared.Ast} they have been turned into well-categorized types
-with an unique identifier like {!type: Scopelang.Ast.ScopeName.t}.
+with an unique identifier like {!type:Shared_ast.ScopeName.t}.
 
 Relevant modules:
 
-{!modules: Surface.Name_resolution Surface.Desugaring}
+{!modules: Desugared.Name_resolution Desugared.From_surface}