docs: fix various mistakes in documentation

docs/design.mld

@@ -17,7 +17,7 @@ We realized there are two distinct use modes when coming to message reporting:
 + One is focusing on {b free-form texts,} which means one directly specifies the long explanation every time a diagnostic is sent; the messages are only a loose categorization of the long explanations.
 + The other is focusing on {b fully structured messages,} which means one directly specifies a structured message (e.g., an element of a variant type) and the long explanation is {i determined} by the message. The message captures all information in the long explanation.
 
-We should support at least the free-form use mode, and ideally support both. The free-form reporting is implemented as {{!module:Asai.Reporter}Reporter} and the structured one is implemented as {{!module:Asai.StructuredReporter}StructuredReporter}.
+We should support at least the free-form use mode, and ideally support both. The free-form reporting is implemented as {{!module:Asai.Reporter}Reporter} and the structured one is implemented as {{!module:Asai.Structured_reporter}Structured_reporter}.
 
 {1 Compositionality: Using Libraries that Use [asai]}
 

src/Asai.mli

@@ -63,5 +63,5 @@ module Source_reader = Source_reader
 (** Helper functions for handling user content. This is exposed for internal testing. Absolutely no stability guarantees. *)
 module String_utils = String_utils
 
-(** The internal flattener that is tightly coupled with {!module:MarkedSource}. This is exposed for internal testing. Absolutely no stability guarantees. *)
+(** The internal flattener that is tightly coupled with {!module:Marked_source}. This is exposed for internal testing. Absolutely no stability guarantees. *)
 module Range_flattener = Range_flattener

src/Marked_source_data.ml

@@ -11,9 +11,9 @@ type 'tag token =
   | String of string
   | Mark of special_position option * 'tag mark
 
-(** A line is a list of {!type:segment}s along with tags. *)
+(** A line is a list of {!type:token}s along with marks. *)
 type 'tag line =
-  { marks : 'tag list (** All tags in this line *)
+  { marks : 'tag list (** All tags attached to this line *)
   ; tokens : 'tag token list
   }
 

src/String_utils.mli

@@ -1,4 +1,3 @@
-(** @include *)
 include module type of String_utils_data
 
 (** [find_eol ~line_breaks read (pos, eof)] returns the end position of the first line and the length of the first newline sequence (if any) within the range [\[pos, end)]. If no newlines are found, then [None] is returned as the length.

src/Structured_reporter_sigs.ml

@@ -7,7 +7,7 @@ sig
   (** The default severity level of a message. Severity levels classify diagnostics into errors, warnings, etc. It is about how serious the {i end user} should take the diagnostic, not whether the program should stop or continue. The severity may be overwritten at the time of issuing a diagnostic. *)
   val default_severity : t -> Diagnostic.severity
 
-  (** The default text of the message. This is the long explanation of the message that the end user would see. You might find helper functions {!val:Text.t} and {!val:Text.tf} useful. The text may be overwritten at the time of issuing a diagnostic. *)
+  (** The default text of the message. This is the long explanation of the message that the end user would see. You might find helper functions {!val:Text.make} and {!val:Text.makef} useful. The text may be overwritten at the time of issuing a diagnostic. *)
   val default_text : t -> Text.t
 
   (** A concise, ideally Google-able string representation of each message. Detailed or long descriptions should be avoided---the shorter, the better. For example, [E001] works better than [type-checking error]. It will be assumed that the string representation has no control characters (such as newline characters). *)

src/Text.mli

@@ -4,7 +4,7 @@
 
     When we render a diagnostic, the layout engine of the diagnostic handler should be the one making layout choices. Therefore, we cannot pass already formatted strings. Instead, a text is defined to be a function that takes a formatter and uses it to render the content. A valid text must satisfy the following two conditions:
     + {b All string (and character) literals must be encoded using UTF-8.}
-    + {b All string (and character) literals must not contain control characters (such as the newline character [\n]).} It is okay to have break hints (such as [@,] and [@ ]) but not literal control characters. This means you should avoid pre-formatted strings, and if you must use them, use {!val:text} to convert newline characters. Control characters include `U+0000-001F` (C0 controls), `U+007F` (backspace) and `U+0080-009F` (C1 controls). These characters are banned because they would mess up the cursor position.
+    + {b All string (and character) literals must not contain control characters (such as the newline character [\n]).} It is okay to have break hints (such as [@,] and [@ ]) but not literal control characters. This means you should avoid pre-formatted strings, and if you must use them, use {!val:make} to convert newline characters. Control characters include `U+0000-001F` (C0 controls), `U+007F` (backspace) and `U+0080-009F` (C1 controls). These characters are banned because they would mess up the cursor position.
 
     {i Pro-tip:} to format a text in another text, use [%t]:
     {[
@@ -26,5 +26,5 @@ val kmakef : (t -> 'b) -> ('a, Format.formatter, unit, 'b) format4 -> 'a
 
 (** {1 Helper Functions} *)
 
-(** A convenience function that converts a {!type:text} into a string by formatting it with the maximum admissible margin and then replacing newlines and indentation with a space character. *)
+(** A convenience function that converts a text into a string by formatting it with the maximum admissible margin and then replacing newlines and indentation with a space character. *)
 val to_string : t -> string

src/tty/Tty.mli

@@ -57,7 +57,7 @@ module Make (Message : Minimum_signatures.Message) : sig
       @param debug Whether to enable the debug mode that performs expensive extra checking. The default is [false].
 
       @raise Invalid_argument if [use_color] is explicitly set to [true] but [use_ansi] is explicitly set to [false], or if [tab_size < 0], or if invalid ranges are detected. When the debug mode is enabled, detection of invalid ranges will raise the more structured exception {!exception:Source_marker.Invalid_range} instead.
-      @raise Invalid_range if the debug mode is enabled and invalid ranges are detected. See {!exception:Source_marker.Invalid_range} for the detailed listing of all possible errors being reported.
+      @raise Source_marker.Invalid_range if the debug mode is enabled and invalid ranges are detected. See {!exception:Source_marker.Invalid_range} for the detailed listing of all possible errors being reported.
 
       @before 0.4.0 The optional parameter [marker] was not present, and angle quotation marks were not used even when ANSI escape sequences are not used.
       @see <https://no-color.org/> for the [NO_COLOR] specification