docs: add some docstrings in various places (#252)

* docs: update some documentation in the Build module

* docs: document what [Scope.resolve] does

* docs: add a toplevel docstring to the Alias module

* docs: document (or not) the bootstrap function

* docs: lightly document the bootstrap module

* fix ignore comment

bootstrap.ml

@@ -1,5 +1,15 @@
 [@@@ocaml.warning "-40"]
 
+(* This module is here to build a version of jbuilder that is capable of
+ * building itself. It accomplishes this by concatenating all its source files
+ * into a single .ml file and simply compiling it. The source code of the
+ * vendored libraries are omitted, being replaced by stubs, just to speed up
+ * the bootstrapping process. This is possible because the features used in
+ * jbuilder's jbuild files use a minimal set of features that do not actually
+ * hit codepaths in which the vendored libraries are used. In order for this to
+ * continue to work, jbuild files in the jbuilder repository should not use
+ * globs. *)
+
 module Array = ArrayLabels
 module List  = ListLabels
 

src/alias.mli

@@ -1,5 +1,8 @@
+(** Rule aliases. *)
+
 open Import
 
+
 type t
 
 val pp : t Fmt.t

src/build.mli

@@ -43,10 +43,16 @@ val vpath : 'a Vspec.t  -> (unit, 'a) t
 
 val dyn_paths : ('a, Path.t list) t -> ('a, 'a) t
 
+(** [contents path] returns an arrow that when run will return the contents of
+    the file at [path]. *)
 val contents : Path.t -> ('a, string) t
+
+(** [lines_of path] returns an arrow that when run will return the contents of
+    the file at [path] as a list of lines. *)
 val lines_of : Path.t -> ('a, string list) t
 
-(** Read lines from a file, unescaping each line using the OCaml conventions *)
+(** [strings path] is like [lines_of path] except each line is unescaped using
+    the OCaml conventions. *)
 val strings : Path.t -> ('a, string list) t
 
 (** Load an S-expression from a file *)

src/jbuild.mli

@@ -21,6 +21,8 @@ module Scope : sig
 
   val empty : t
 
+  (** [resolve t package_name] looks up [package_name] in [t] and returns the
+      package description if it exists, otherwise it returns an error. *)
   val resolve : t -> string -> (Package.t, string) result
 end
 

src/main.mli

@@ -13,6 +13,8 @@ type setup =
 (* Returns [Error ()] if [pkg] is unknown *)
 val package_install_file : setup -> string -> (Path.t, unit) result
 
+(** Scan the source tree and discover everything that's needed in order to build
+    it. *)
 val setup
   :  ?log:Log.t
   -> ?filter_out_optional_stanzas_with_missing_deps:bool
@@ -28,6 +30,9 @@ val external_lib_deps
   -> Build.lib_deps Path.Map.t
 val report_error : ?map_fname:(string -> string) -> Format.formatter -> exn -> unit
 
-val bootstrap : unit -> unit
-
 val find_context_exn : setup -> name:string -> Context.t
+
+(**/**)
+
+(* This is used to bootstrap jbuilder itself. It is not part of the public API. *)
+val bootstrap : unit -> unit