Allow to escape newline with \ like in markdown

clap_derive/src/utils/doc_comments.rs

@@ -55,7 +55,7 @@ pub fn process_doc_comment(lines: Vec<String>, name: &str, preprocess: bool) ->
         ]
     } else {
         let short = if preprocess {
-            let s = merge_lines(&lines);
+            let s = process_paragraph(&lines);
             remove_period(s)
         } else {
             lines.join("\n")
@@ -83,14 +83,64 @@ fn split_paragraphs(lines: &[&str]) -> Vec<String> {
         last_line += start + len;
 
         if len != 0 {
-            Some(merge_lines(&slice[..len]))
+            Some(process_paragraph(&slice[..len]))
         } else {
             None
         }
     })
     .collect()
 }
 
+fn process_paragraph(lines: &[&str]) -> String {
+    lines
+        .iter()
+        .map(|ln| ln.trim())
+         // Ignore empty lines even if they were escaped with slash
+        .filter(|ln| ln != &"\\" && !ln.is_empty())
+        // Run actual slash escaping
+        .map(|ln| {
+            let expected_len = ln.len() + 1;
+            let mut chars = ln.chars();
+            let mut ln = String::with_capacity(expected_len);
+            while let Some(c) = chars.next() {
+                if c == '\\' {
+                     match chars.next() {
+                        // Escape slash with slash
+                        Some('\\') => {
+                            ln.push('\\')
+                        },
+                        // Don't escape other letters
+                        Some(x) => {
+                            ln.push('\\');
+                            ln.push(x);
+                        },
+                        // Escape newline
+                        None => {
+                            // Remove whitespace so it wouldn't
+                            // mess with terminal wrapping
+                            ln = trim_end(ln);
+                            ln.push('\n');
+                            return ln
+                        },
+                    }
+                } else {
+                    ln.push(c);
+                }
+            }
+            // Since every line is trimmed we need
+            // this space to avoid gluing words together
+            ln.push(' ');
+            ln
+        })
+        .collect()
+}
+
+fn trim_end(mut s: String) -> String {
+    let while_text = s.trim_end_matches(|c: char| c.is_ascii_whitespace()).len();
+    s.truncate(while_text);
+    s
+}
+
 fn remove_period(mut s: String) -> String {
     if s.ends_with('.') && !s.ends_with("..") {
         s.pop();
@@ -101,7 +151,3 @@ fn remove_period(mut s: String) -> String {
 fn is_blank(s: &str) -> bool {
     s.trim().is_empty()
 }
-
-fn merge_lines(lines: &[&str]) -> String {
-    lines.iter().map(|s| s.trim()).collect::<Vec<_>>().join(" ")
-}