Repository: tweag/nickel (rust)

Issue:
The markdown `nickel doc` output prints some spurious backslashes
**Describe the bug**

`nickel doc`'s markdown output contains some backlashes that mess up with the rendering. For instance, `{ x : Number = 1, y | doc "Blah" }` will be rendered as

```markdown
# `x`

- `x : Number`
\
# `y`

\
Blah
```

`cmark` as well as GitHub's markdown renderer and `pandoc --from=commonmark` will show (some of) these backslashes literally:

![image](https://github.com/tweag/nickel/assets/7226587/c9748cc9-3a5d-46cb-82a8-6e303b95a2d2)

Pandoc's own markdown format won't render them but interpret them as escaping the start of the next line:

![image](https://github.com/tweag/nickel/assets/7226587/3bf0a157-df5e-4577-8fda-9a5a0de4592e)

**To Reproduce**

```console
$ nickel doc --stdout <<<'{ x : Number = 1, y | doc "Blah" }' | cmark
```

**Expected behavior**

An output that is at least commonmark-compatible (and if possible compatible with other common markdown dialects like gfm or pandoc)

**Environment**
 - OS name + version:
 - Version of the code: 28672ee45bfe78dc3dc828ac1fe4fa40f99965e9

**Additional context**
Add any other context about the problem here.


Pull request:
Markdown documentation generation: do not insert line breaks
Fixes #1706.

The code generating markdown documentation from a Nickel configuration used to unconditionally insert hard line breaks between a field's signature and the rest of its documentation. However, one can't insert a hard line break immediately followed by a blocks in commonmark (or put differently: it's not representable as a source), and those line breaks were just rendered as spurious backslashes at best, or sometimes interpreted differently (see #1706 for more details).

A bit of experimentation showed that what comes after this line break is always a block in the sense of commonmark (even when it's simple documentation text, it's wrapped as a Markdown paragraph). Thus this PR just removes the line break altogether, which is not useful and never legal anyway.

Patch:
diff --git a/core/src/program.rs b/core/src/program.rs
index 0325345a..52e5ff9a 100644
--- a/core/src/program.rs
+++ b/core/src/program.rs
@@ -789,8 +789,6 @@ mod doc {
                     ))
                 }
 
-                document.append(arena.alloc(AstNode::from(NodeValue::LineBreak)));
-
                 if let Some(ref doc) = field.documentation {
                     document.append(parse_markdown_string(header_level + 1, arena, doc, options));
                 }


Test patch:
diff --git a/cli/tests/snapshot/snapshots/snapshot__doc_stdout_record.ncl.snap b/cli/tests/snapshot/snapshots/snapshot__doc_stdout_record.ncl.snap
index 7c5138bd..b7229c9d 100644
--- a/cli/tests/snapshot/snapshots/snapshot__doc_stdout_record.ncl.snap
+++ b/cli/tests/snapshot/snapshots/snapshot__doc_stdout_record.ncl.snap
@@ -4,6 +4,4 @@ expression: out
 ---
 # `Hello`
 
-\
 World\!
-
diff --git a/cli/tests/snapshot/snapshots/snapshot__doc_stdout_types.ncl.snap b/cli/tests/snapshot/snapshots/snapshot__doc_stdout_types.ncl.snap
index fe1e456f..ecb7563c 100644
--- a/cli/tests/snapshot/snapshots/snapshot__doc_stdout_types.ncl.snap
+++ b/cli/tests/snapshot/snapshots/snapshot__doc_stdout_types.ncl.snap
@@ -6,6 +6,4 @@ expression: out
 
 - `Hello : Number`
 - `Hello | std.string.Stringable`
-\
 World\!
-