diff --git a/src/Asai.mli b/src/Asai.mli index 06bfffb..9527b03 100644 --- a/src/Asai.mli +++ b/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 diff --git a/src/Marked_source_data.ml b/src/Marked_source_data.ml index c2c45be..c5375e0 100644 --- a/src/Marked_source_data.ml +++ b/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 } diff --git a/src/String_utils.mli b/src/String_utils.mli index 73677ec..292821e 100644 --- a/src/String_utils.mli +++ b/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. diff --git a/src/Structured_reporter_sigs.ml b/src/Structured_reporter_sigs.ml index 8d5df4d..2906cfc 100644 --- a/src/Structured_reporter_sigs.ml +++ b/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). *) diff --git a/src/Text.mli b/src/Text.mli index f942264..1e1721e 100644 --- a/src/Text.mli +++ b/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 diff --git a/src/tty/Tty.mli b/src/tty/Tty.mli index 070570f..04eeaa4 100644 --- a/src/tty/Tty.mli +++ b/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 for the [NO_COLOR] specification