Merge pull request #1023 from stan-dev/module-doc-cleanup

WardBrian · web-flow · commit 3699f248ae6d · 2021-11-03T16:59:09.000-04:00
Update module docs
diff --git a/src/common/Fixed.ml b/src/common/Fixed.ml
@@ -1,6 +1,7 @@
 (** This module defines the signatures and [Make] functors for the 'fixed point'
     (or two-level) type we use for our intermediate representations
 *)
+
 open Core_kernel
 
 (** The fixed-point of [Pattern.t] annotated with some meta-data *)
diff --git a/src/common/Gensym.mli b/src/common/Gensym.mli
@@ -1,3 +1,8 @@
+(** Generate fresh (never before used) symbols.
+
+Uses an internal (mutable) counter
+*)
+
 val generate : ?prefix:string -> unit -> string
 val enter : unit -> string * (unit -> unit)
 val reset_danger_use_cautiously : unit -> unit
diff --git a/src/common/Specialized.ml b/src/common/Specialized.ml
@@ -7,6 +7,7 @@ This specialization is useful since we end up with a concrete type of kind [*]
 the analysis and optimization code, we work with map's and sets of our IR types
 a lot and this approach makes the types much nicer to work with.
 *)
+
 open Core_kernel
 
 (** Signature of all meta data used to annotate IRs *)
diff --git a/src/frontend/Input_warnings.mli b/src/frontend/Input_warnings.mli
@@ -1,3 +1,7 @@
+(** A module to contain the mutable state used to track warnings from the
+    parser and lexer.
+*)
+
 val init : unit -> unit
 (** As something of a hack, Input_warnings keeps track of which warnings the lexer has
     emitted as a form of hidden state, which must be initialized and [collect]ed.*)
diff --git a/src/frontend/Parse.mli b/src/frontend/Parse.mli
@@ -1,5 +1,6 @@
 (** Some complicated stuff to get the custom syntax errors out of Menhir's Incremental
     API *)
+
 open Core_kernel
 
 val parse_file :
diff --git a/src/frontend/Pretty_printing.ml b/src/frontend/Pretty_printing.ml
@@ -16,12 +16,12 @@ let get_comments end_loc =
   let rec go ls =
     match ls with
     | LineComment (s, ({Middle.Location_span.begin_loc; _} as loc)) :: tl
-      when Middle.Location.compare_loc begin_loc end_loc < 0 ->
+      when Middle.Location.compare begin_loc end_loc < 0 ->
         (false, [s], loc) :: go tl
     | BlockComment (s, ({Middle.Location_span.begin_loc; _} as loc)) :: tl
-      when Middle.Location.compare_loc begin_loc end_loc < 0 ->
+      when Middle.Location.compare begin_loc end_loc < 0 ->
         (true, s, loc) :: go tl
-    | Comma loc :: tl when Middle.Location.compare_loc loc end_loc < 0 -> go tl
+    | Comma loc :: tl when Middle.Location.compare loc end_loc < 0 -> go tl
     | _ ->
         comments := ls ;
         []
@@ -32,10 +32,10 @@ let get_comments_until_comma end_loc =
   let rec go ls =
     match ls with
     | LineComment (s, ({Middle.Location_span.begin_loc; _} as loc)) :: tl
-      when Middle.Location.compare_loc begin_loc end_loc < 0 ->
+      when Middle.Location.compare begin_loc end_loc < 0 ->
         (false, [s], loc) :: go tl
     | BlockComment (s, ({Middle.Location_span.begin_loc; _} as loc)) :: tl
-      when Middle.Location.compare_loc begin_loc end_loc < 0 ->
+      when Middle.Location.compare begin_loc end_loc < 0 ->
         (true, s, loc) :: go tl
     | _ ->
         comments := ls ;
diff --git a/src/frontend/Warnings.mli b/src/frontend/Warnings.mli
@@ -1,3 +1,5 @@
+(** Used for user-facing warning messages *)
+
 type t = Middle.Location_span.t * string
 
 val pp : ?printed_filename:string -> t Fmt.t
diff --git a/src/middle/Compiler.ml b/src/middle/Compiler.ml
diff --git a/src/middle/Expr.mli b/src/middle/Expr.mli
@@ -1,3 +1,5 @@
+(** MIR types and modules corresponding to the expressions of the language *)
+
 open Core_kernel
 open Common
 
diff --git a/src/middle/Fun_kind.ml b/src/middle/Fun_kind.ml
@@ -1,3 +1,7 @@
+(** Types for function kinds, e.g. [StanLib] or [UserDefined], and
+  function suffix types, e.g. [foo_ldfp], [bar_lp]
+*)
+
 open Core_kernel
 
 type 'propto suffix = FnPlain | FnRng | FnLpdf of 'propto | FnTarget
diff --git a/src/middle/Index.ml b/src/middle/Index.ml
@@ -1,3 +1,5 @@
+(** Types of indexing operations *)
+
 open Core_kernel
 
 type 'a t =
diff --git a/src/middle/Internal_fun.ml b/src/middle/Internal_fun.ml
@@ -1,3 +1,5 @@
+(** Language functions defined internally by the compiler *)
+
 open Core_kernel
 
 type 'expr t =
diff --git a/src/middle/Location.ml b/src/middle/Location.ml
@@ -1,12 +1,19 @@
+(** Storing locations in the original source *)
+
 open Core_kernel
+
+(**/**)
+
 module Str = Re.Str
 
+(**/**)
+
 (** Source code locations *)
 type t =
   {filename: string; line_num: int; col_num: int; included_from: t option}
-[@@deriving sexp, hash, compare]
+[@@deriving sexp, hash]
 
-let compare_loc loc1 loc2 =
+let compare loc1 loc2 =
   let rec unfold = function
     | {included_from= None; _} as loc -> [loc]
     | {included_from= Some loc1; _} as loc2 -> loc2 :: unfold loc1
@@ -24,6 +31,7 @@ let compare_loc loc1 loc2 =
   in
   go (List.rev (unfold loc1), List.rev (unfold loc2))
 
+(** Will attempt to {b open} the file and*)
 let pp_context_exn ppf {filename; line_num; col_num; _} =
   let open In_channel in
   let input = create filename in
diff --git a/src/middle/Location_span.ml b/src/middle/Location_span.ml
@@ -1,6 +1,6 @@
-open Core_kernel
+(** Delimited locations in source code *)
 
-(** Delimited locations *)
+open Core_kernel
 
 type t = {begin_loc: Location.t; end_loc: Location.t}
 [@@deriving sexp, hash, compare]
diff --git a/src/middle/Operator.ml b/src/middle/Operator.ml
@@ -1,3 +1,5 @@
+(** Utilities for Stan's built in operators *)
+
 open Core_kernel
 
 type t =
diff --git a/src/middle/Poly_compare_temp.ml b/src/middle/Poly_compare_temp.ml
diff --git a/src/middle/Program.ml b/src/middle/Program.ml
@@ -1,3 +1,5 @@
+(** Defines the core of the MIR *)
+
 open Core_kernel
 open Common
 open Helpers
diff --git a/src/middle/SizedType.ml b/src/middle/SizedType.ml
@@ -1,3 +1,5 @@
+(** Types which have a concrete size associated, e.g. [vector\[n\]] *)
+
 open Core_kernel
 open Common
 
diff --git a/src/middle/Stmt.mli b/src/middle/Stmt.mli
@@ -1,3 +1,5 @@
+(** MIR types and modules corresponding to the statements of the language *)
+
 open Core_kernel
 open Common
 open Label
diff --git a/src/middle/Transformation.ml b/src/middle/Transformation.ml
@@ -1,4 +1,7 @@
 (** Transformations (constraints) for global variable declarations *)
+
+(** Types of transformations. Polymorphic type is filled
+in with an expression fixed-point, e.g. {!type:Frontend.Ast.typed_expression} *)
 type 'e t =
   | Identity
   | Lower of 'e
diff --git a/src/middle/Type.ml b/src/middle/Type.ml
@@ -1,3 +1,5 @@
+(** A type which unifies [SizedTypes] and [UnsizedTypes] for declarations *)
+
 open Common
 
 type 'a t = Sized of 'a SizedType.t | Unsized of UnsizedType.t
diff --git a/src/middle/UnsizedType.ml b/src/middle/UnsizedType.ml
@@ -1,3 +1,5 @@
+(** Types which have dimensionalities but not sizes, e.g. [array\[,,\]] *)
+
 open Core_kernel
 open Common.Helpers
 
diff --git a/src/middle/Utils.ml b/src/middle/Utils.ml
@@ -1,3 +1,5 @@
+(** Utilities, primarily surrounding distribution names and suffixes *)
+
 open Core_kernel
 
 let option_or_else ~if_none x = Option.first_some x if_none
diff --git a/src/stan_math_backend/Locations.mli b/src/stan_math_backend/Locations.mli
@@ -1,3 +1,6 @@
+(** Create messages used in the C++ for providing locations in the Stan
+code when an error occurs *)
+
 open Middle
 
 type state_t
diff --git a/src/stan_math_backend/Mangle.ml b/src/stan_math_backend/Mangle.ml
@@ -1,3 +1,17 @@
+(** Mangle variables which are C++ reserved words into
+    valid C++ identifiers.
+
+    This is done in Transform_Mir. When one of these
+    names is emitted as a string, we use remove_prefix
+    such that this mangling is opaque to the user -
+    e.g., a cmdstan output file would still have a column
+    called "public", even if internally we called this
+    "_stan_public"
+
+    NB: the use of a leading _ is essential, because
+    the lexer won't allow this in a user-created variable.
+*)
+
 open Core_kernel
 
 let kwrds_prefix = "_stan_"
diff --git a/src/stan_math_backend/Transform_Mir.mli b/src/stan_math_backend/Transform_Mir.mli
@@ -1,3 +1,7 @@
+(** Perform backend-specific transformations of the MIR
+such as mangling or renaming of functions which differ in
+the library implementation *)
+
 open Middle
 
 val trans_prog : Program.Typed.t -> Program.Typed.t

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+(** Used for user-facing warning messages *)`
	`2`	`+`
`1`	`3`	`type t = Middle.Location_span.t * string`
`2`	`4`
`3`	`5`	`val pp : ?printed_filename:string -> t Fmt.t`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+(** MIR types and modules corresponding to the expressions of the language *)`
	`2`	`+`
`1`	`3`	`open Core_kernel`
`2`	`4`	`open Common`
`3`	`5`