Newlines removed in move from doc comment to OpenAPI description

[david-crespo]

Seems like double newlines are being kept but single newlines are being turned into spaces.

/// Note that any gaps, unsorted bins, or non-finite values will result in an error.
///
/// Example
/// -------
/// ```rust
/// use oximeter::histogram::{BinRange, Histogram};

https://github.com/oxidecomputer/omicron/blob/e9554ad930665e82526b784b1f12300f067298fa/oximeter/oximeter/src/histogram.rs#L201-L222

becomes

an error.\n\nExample ------- ```rust use oximeter::histogram::{BinRange, Histogram};\n\nlet edges

https://github.com/oxidecomputer/omicron/blob/e9554ad930665e82526b784b1f12300f067298fa/openapi/nexus.json#L8018

[ahl]

Tricky! It's hard to distinguish, say, a line-wrapped paragraph from intentional newlines. In this particular case, it seems like the comments are intended for the local crate and aren't appropriate to include in the OpenAPI document at all.

[bnaecker]

Yeah, this particular comment predates using a generator, and wasn't originally intended to be part of the OpenAPI spec. I think this one deserves either a wrapper type with a more clear and language-agnostic docstring, or moving most of the existing string to a private comment, e.g., /// to // in the source file.

[david-crespo]

Fine with me, seems like most of the fix here is to fix the comment itself.

Maybe a dumb question, but why do we need to process the newlines in the doc comments at all?

dropshot/dropshot_endpoint/src/lib.rs

Lines 523 to 549 in e75844e

	match (summary, first) {
	(None, _) => (None, None),
	(summary, None) => (summary, None),
	(Some(summary), Some(first)) => (
	Some(summary),
	Some(
	lines
	.fold(first, |acc, comment| {
	if acc.ends_with('-')
	|| acc.ends_with('\n')
	|| acc.is_empty()
	{
	// Continuation lines and newlines.
	format!("{}{}", acc, comment)
	} else if comment.is_empty() {
	// Handle fully blank comments as newlines we keep.
	format!("{}\n", acc)
	} else {
	// Default to space-separating comment fragments.
	format!("{} {}", acc, comment)
	}
	})
	.trim_end()
	.to_string(),
	),
	),
	}