Docs: wrap files.

Author: bjones1

server/src/ide/filewatcher.rs

@@ -783,7 +783,8 @@ mod tests {
                 m
             }
             _ = sleep(Duration::from_secs(3)) => {
-                // The backtrace shows what message the code was waiting for; otherwise, it's an unhelpful error message.
+                // The backtrace shows what message the code was waiting for;
+                // otherwise, it's an unhelpful error message.
                 panic!("Timeout waiting for message:\n{}", Backtrace::force_capture());
             }
         }

server/src/lexer.rs

@@ -15,22 +15,22 @@
 // [http://www.gnu.org/licenses](http://www.gnu.org/licenses).
 //
 // `c.pest` - Pest parser definition for the C language
-// ====================================================
+// =============================================================================
 //
 // Comments
-// --------
+// -----------------------------------------------------------------------------
 doc_block = _{ inline_comment | block_comment }
 
-// Per the [C standard, section
-// 6.4.3](https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3220.pdf#page=65),
+// Per the
+// [C standard, section 6.4.3](https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3220.pdf#page=65),
 // "white-space consists of: (space, horizontal tab, new-line, vertical tab, and
 // form-feed)." Omit newlines, since the rest of this parser uses these.
 vertical_tab = { "\x0B" }
 form_feed    = { "\x0C" }
 white_space  = { (" " | "\t" | vertical_tab | form_feed)* }
 
-// The [C standard, section
-// 6.4.9](https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3220.pdf#page=65),
+// The
+// [C standard, section 6.4.9](https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3220.pdf#page=65),
 // defines inline and block comments.
 //
 // ### Inline comments
@@ -50,110 +50,106 @@ block_comment_closing_delim_1 =  { unused }
 block_comment_closing_delim_2 =  { unused }
 
 // Code
-// ----
+// -----------------------------------------------------------------------------
 //
-// Per the [C standard, section
-// 5.1.1.2](https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3220.pdf#page=24),
+// Per the
+// [C standard, section 5.1.1.2](https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3220.pdf#page=24),
 // if a line of code ends with a backslash, it continues on the next line. This
 // is a logical line; treat it as a single line. Therefore, consider a
 // backslash-newline (or anything that's not a newline) a part of the current
 // logical line. Note that this parser doesn't apply this rule to comments
 // (which, per the spec, it should) for several reasons:
 //
-// 1.  Comments continued onto another line don't look like a comment; this
-//     would confuse most developers.
-//
-// 2.  The backslash-newline in a comment creates a [hard line
-//     break](https://spec.commonmark.org/0.31.2/#hard-line-breaks) in Markdown,
-//     which means inserting a hard line break this way in an inline comment
-//     requires the next line to omit the inline comment delimiters. For
-//     example: 
-//
-//     ```C
-//     // This is a hard line break\
-//     followed by a comment which must not include the // inline comment
-//     // delimiter on the line after the line break, but which must
-//     include them on following lines.
-//     ```
-//
-// 3.  The CodeChat Editor web-to-code function produces incorrect results in
-//     this case, adding a comment delimiter when it shouldn't. To fix this, it
-//     would have to look for a backslash newline only in C/C++-like languages.
+// 1. Comments continued onto another line don't look like a comment; this would
+//    confuse most developers.
+//
+// 2. The backslash-newline in a comment creates a
+//    [hard line break](https://spec.commonmark.org/0.31.2/#hard-line-breaks) in
+//    Markdown, which means inserting a hard line break this way in an inline
+//    comment requires the next line to omit the inline comment delimiters. For
+//    example: 
+//
+//    ```C
+//    // This is a hard line break\
+//    followed by a comment which must not include the // inline comment
+//    // delimiter on the line after the line break, but which must
+//    include them on following lines.
+//    ```
+//
+// 3. The CodeChat Editor web-to-code function produces incorrect results in
+//    this case, adding a comment delimiter when it shouldn't. To fix this, it
+//    would have to look for a backslash newline only in C/C++-like languages.
 logical_line_char   = _{ ("\\" ~ NEWLINE) | not_newline }
 code_line_token = _{ logical_line_char }
 
 // Dedenter
-// --------
+// -----------------------------------------------------------------------------
 //
 // This parser runs separately; it dedents block comments. There are several
 // cases:
 //
-// *   A single line: `/* comment */`. No special handling needed.
-// *   Multiple lines, in two styles.
-//     *   Each line of the comment is not consistently whitespace-indented. No
-//         special handling needed. For example:
-//
-//         ```C
-//         /* This is
-//           not
-//            consistently indented. */
-//         ```
-//
-//     *   Each line of the comment is consistently whitespace-indented; for
-//         example:
-//
-//         ```C
-//         /* This is
-//            consistently indented. */
-//         ```
-//
-//         Consistently indented means the first non-whitespace character on a
-//         line aligns with, but never comes before, the comment's start.
-//         Another example:
-//
-//         ```C
-//         /* This is
-//            correct
-//
-//            indentation.
-//          */
-//         ```
-//
-//         Note that the third (blank) line doesn't have an indent; since that
-//         line consists only of whitespace, this is OK. Likewise, the last line
-//         (containing the closing comment delimiter of `*/`) consists only of
-//         whitespace after the comment delimiters are removed.
-//
-//     *   Each line of the comment is consistently asterisk-indented; for
-//         example:
-//
-//         ```C
-//         /* This is
-//          * correct
-//          *
-//          * indentation.
-//          */
-//         ```
-//
-//         Note that in this case, no whitespace-only lines are allowed.
-//         Instead, the special case is lines which have a newline immediately
-//         after the `*`.
+// * A single line: `/* comment */`. No special handling needed.
+// * Multiple lines, in two styles.
+//   * Each line of the comment is not consistently whitespace-indented. No
+//     special handling needed. For example:
+//
+//     ```C
+//     /* This is
+//       not
+//        consistently indented. */
+//     ```
+//
+//   * Each line of the comment is consistently whitespace-indented; for
+//     example:
+//
+//     ```C
+//     /* This is
+//        consistently indented. */
+//     ```
+//
+//     Consistently indented means the first non-whitespace character on a line
+//     aligns with, but never comes before, the comment's start. Another
+//     example:
+//
+//     ```C
+//     /* This is
+//        correct
+//
+//        indentation.
+//      */
+//     ```
+//
+//     Note that the third (blank) line doesn't have an indent; since that line
+//     consists only of whitespace, this is OK. Likewise, the last line
+//     (containing the closing comment delimiter of `*/`) consists only of
+//     whitespace after the comment delimiters are removed.
+//
+//   * Each line of the comment is consistently asterisk-indented; for example:
+//
+//     ```C
+//     /* This is
+//      * correct
+//      *
+//      * indentation.
+//      */
+//     ```
+//
+//     Note that in this case, no whitespace-only lines are allowed. Instead,
+//     the special case is lines which have a newline immediately after the `*`.
 //
 // To implement this dedenting, we must have two paths to accepting the contents
 // of a block comment. Otherwise, this parser rejects the block (it cannot be
 // dedented). The approach:
 //
-// 1.  The space-indented path. This requires:
-//     1.  The first line ends with a newline. (`valid_first_line`)
-//     2.  Non-first lines with contents must be properly indented. If a
-//         non-first line ends in a newline, it must not be the last line.
-//         (`dedented_line`)
-//     3.  A whitespace-only line must not be the last line, unless it has
-//         exactly the indent needed to align the closing comment delimiter
-//         (`last_line`).
-// 2.  The asterisk-indented path. The requirements are the same as the
-//     space-indented path, though the proper indent includes an asterisk in the
-//     correct location.
+// 1. The space-indented path. This requires:
+//    1. The first line ends with a newline. (`valid_first_line`)
+//    2. Non-first lines with contents must be properly indented. If a non-first
+//       line ends in a newline, it must not be the last line. (`dedented_line`)
+//    3. A whitespace-only line must not be the last line, unless it has exactly
+//       the indent needed to align the closing comment delimiter (`last_line`).
+// 2. The asterisk-indented path. The requirements are the same as the
+//    space-indented path, though the proper indent includes an asterisk in the
+//    correct location.
 dedenter = {
     SOI ~ indent ~ valid_first_line ~ (valid_space_line+ | valid_star_line+) ~ DROP ~ EOI
 }

server/src/lexer/pest/c.pest

@@ -1,54 +1,53 @@
 Parser design
-=============
+================================================================================
 
 The CodeChat Editor uses the [Pest parser](https://pest.rs/), a Rust
 implementation of a parsing expression grammar (or PEG). The purpose of the
 parser from a CodeChat Editor perspective is to classify a source file into code
 blocks and doc blocks. To accomplish this goal, grammar files (`.pest`) are
 divided into:
 
-*   A shared grammar ([shared.pest](shared.pest)), which contains basic
-    definitions applicable to all languages;
-*   A language-specific grammar, which builds on these shared definitions by
-    providing necessary language-specific customizations.
+* A shared grammar ([shared.pest](shared.pest)), which contains basic
+  definitions applicable to all languages;
+* A language-specific grammar, which builds on these shared definitions by
+  providing necessary language-specific customizations.
 
 In particular, a language-specific grammar must provide:
 
-*   The definition of a `doc_block`; for most languages, `doc_block = _{
-    inline_comment | block_comment }`. However, languages which lack an inline
-    comment (such as CSS) or a block comment (such as Python) would contain only
-    the appropriate comment type.
+* The definition of a `doc_block`; for most languages, `doc_block = _{
+  inline_comment | block_comment }`. However, languages which lack an inline
+  comment (such as CSS) or a block comment (such as Python) would contain only
+  the appropriate comment type.
 
-*   Inline comment definitions:
+* Inline comment definitions:x
 
-    *   Opening inline delimiter(s) supported by the language. Three inline
-        comment delimiters must be defined for a language. For C, this is:
+  * Opening inline delimiter(s) supported by the language. Three inline comment
+    delimiters must be defined for a language. For C, this is:
 
-        ```
-        inline_comment_delims  = _{ inline_comment_delim_0 }
-        inline_comment_delim_0 =  { "//" }
-        inline_comment_delim_1 =  { unused }
-        inline_comment_delim_2 =  { unused }
-        ```
-
-    *   A token which defines characters in the body of on an inline comment.
-        For Python, this is:
-
-        ```
-        inline_comment_char = { not_newline }
-        ```
+    ```
+    inline_comment_delims  = _{ inline_comment_delim_0 }
+    inline_comment_delim_0 =  { "//" }
+    inline_comment_delim_1 =  { unused }
+    inline_comment_delim_2 =  { unused }
+    ```
 
-*   Block comment definitions: provide opening and closing delimiter
-    definitions. For C, this is:
+  * A token which defines characters in the body of on an inline comment. For
+    Python, this is:
 
     ```
-    block_comment                 =  { block_comment_0 }
-    block_comment_opening_delim_0 =  { "/*" }
-    block_comment_opening_delim_1 =  { unused }
-    block_comment_opening_delim_2 =  { unused }
-    block_comment_closing_delim_0 =  { "*/" }
-    block_comment_closing_delim_1 =  { unused }
-    block_comment_closing_delim_2 =  { unused }
+    inline_comment_char = { not_newline }
     ```
-
-*   `code_line_token`, a token used to recognize tokens in a code line.
+* Block comment definitions: provide opening and closing delimiter definitions.
+  For C, this is:
+
+  ```
+  block_comment                 =  { block_comment_0 }
+  block_comment_opening_delim_0 =  { "/*" }
+  block_comment_opening_delim_1 =  { unused }
+  block_comment_opening_delim_2 =  { unused }
+  block_comment_closing_delim_0 =  { "*/" }
+  block_comment_closing_delim_1 =  { unused }
+  block_comment_closing_delim_2 =  { unused }
+  ```
+
+* `code_line_token`, a token used to recognize tokens in a code line.

server/src/lexer/pest/parser_design.md

@@ -15,29 +15,29 @@
 // [http://www.gnu.org/licenses](http://www.gnu.org/licenses).
 //
 // `python.pest` - Pest parser definition for Python
-// =================================================
+// =============================================================================
 doc_block = _{ inline_comment }
 
-// Per the [Python language
-// reference](https://docs.python.org/3/reference/lexical_analysis.html#indentation),
+// Per the
+// [Python language reference](https://docs.python.org/3/reference/lexical_analysis.html#indentation),
 // leading whitespace used to determine the indentation level consists of spaces
 // and tabs.
 white_space = { (" " | "\t")* }
 
 // Inline comments
-// ---------------
+// -----------------------------------------------------------------------------
 inline_comment_delims  = _{ inline_comment_delim_0 }
 inline_comment_delim_0 =  { "#" }
 inline_comment_delim_1 =  { unused }
 inline_comment_delim_2 =  { unused }
-// Per the [Python language reference, section
-// 2.1.3](https://docs.python.org/3/reference/lexical_analysis.html#comments),
+// Per the
+// [Python language reference, section 2.1.3](https://docs.python.org/3/reference/lexical_analysis.html#comments),
 // comments end at the end of a physical line. There's no C-like backslash that
 // can join physical lines into logical lines for comments.
 inline_comment_char = { not_newline }
 
 // Block comments
-// --------------
+// -----------------------------------------------------------------------------
 //
 // Other languages support block comments; even though Python doesn't, the
 // following must be defined. Block comments never combine.
@@ -50,7 +50,7 @@ block_comment_closing_delim_1 = { unused }
 block_comment_closing_delim_2 = { unused }
 
 // Code blocks
-// -----------
+// -----------------------------------------------------------------------------
 code_line_token = _{ long_string | short_string | not_newline }
 long_string     = _{
     // The opening string delimiter.
@@ -73,7 +73,7 @@ short_string = _{
 }
 
 // Dedenter
-// --------
+// -----------------------------------------------------------------------------
 dedenter = { unused }
 
 /// CodeChat Editor lexer: cpp.