Handling of newline in RustDoc

[ralpha]

Should or should we not change the default parsing behavior from the current (removing single \n in RustDoc)
to just leaving the newline in.

To clarify for everyone we are talking about:

/// Some documentation
/// on multiple lines
/// right here.
/// 
/// This is a new paragraph.
struct Test{
   // ...
}

Should this result in:

"Some documentation on multiple lines right here.\n\nThis is a new paragraph." // Current (2021/11/25)
// or
"Some documentation\non multiple lines\nright here.\n\nThis is a new paragraph." // If we change is back

This question came up in: #38

The intention is that it removes extraneous newlines from simple text doc comments, since they may be spread across multiple lines just to keep the line length of the original Rust source reasonable, which ideally wouldn't affect any generated schema. However, this does indeed mangle more complex markdown e.g. code blocks and lists, so it might be doing more harm than good... I'm definitely considering removing this behaviour, and passing down the docstring unaltered as you suggest

#38 (comment)

A Visitor can be created to do this behavior and users can enable or disable it as they want.
But the default has to be one way or the other. (to be decided in this issue)

[blake-mealey]

As I described in #129, I would personally like the default behaviour to use the raw doc comment. It should definitely be an option at least. For my project I am currently working off of a fork to get this functionality: diff

I'd be happy to submit a PR for this. Please let me know what you'd like to see implemented

[abonander]

There's really no good reason to strip excess newlines. By the CommonMark spec, these should already be treated as soft line breaks and handled during rendering: https://spec.commonmark.org/0.30/#softbreak

[lorenzolewis]

What about if we want the new lines? For instance, I have the following in my docs:

/// HTTP API scope definition.
/// It is a list of URLs that can be accessed by the webview when using the HTTP APIs.
/// The scoped URL is matched against the request URL using a glob pattern.
///
/// Examples:
/// 
///  - "https://**": allows all HTTPS urls
///  - "https://*.github.com/tauri-apps/tauri": allows any subdomain of "github.com" with the "tauri-apps/api" path
///  - "https://myapi.service.com/users/*": allows access to any URLs that begins with "https://myapi.service.com/users/"

and I want to explicitly have the new lines come through so the bullet points get rendered out correctly. Would there be a keyword per line I could use to "opt-in" for a new line?

[tweidinger]

Hey @GREsau 👋
I saw you are recently pushing for a 1.0 release and requested feedback on issues for specific API changes so I want to re-raise your attention to this set of issues. We currently use schemars in Tauri for improving our reference documentation of configuration files.
Our process is rustdoc->json-schema->markdown->website content (🙃)

For this purpose we have multiline rustdoc comments with markdown, examples and more complex content. As newlines get stripped and this breaks our process and we needed to temporary fork this crate to "unbrick". We would be willing to provide a PR or support you wherever needed on this topic. We tried to solve it with a custom visitor but the newline removal happened before the custom visitor sees the data.

Any chance for this to be configurable and to land in the 1.0 release?

Right now we naively disabled the newline stripping in the temporary fork.

[GREsau]

Finally, as of schemars v1.0.0-alpha.3, whitespace from doc comments is no longer collapsed when generating a schema's description 🙂

[abonander]

What about if we want the new lines? For instance, I have the following in my docs:

/// HTTP API scope definition.
/// It is a list of URLs that can be accessed by the webview when using the HTTP APIs.
/// The scoped URL is matched against the request URL using a glob pattern.
///
/// Examples:
/// 
///  - "https://**": allows all HTTPS urls
///  - "https://*.github.com/tauri-apps/tauri": allows any subdomain of "github.com" with the "tauri-apps/api" path
///  - "https://myapi.service.com/users/*": allows access to any URLs that begins with "https://myapi.service.com/users/"

and I want to explicitly have the new lines come through so the bullet points get rendered out correctly. Would there be a keyword per line I could use to "opt-in" for a new line?

@lorenzolewis this is obviously quite a bit late, but for posterity: you can get a hard line break by leaving two trailing spaces at the end of the line. It's in the same section of the Commonmark spec I linked before:

A regular line ending (not in a code span or HTML tag) that is not preceded by two or more spaces or a backslash is parsed as a softbreak.

(Emphasis mine.)