Doc comment block should strip leading asterisk (*)

[kjeremy]

In looking at struct ClientCapabilities of lsp-types defined as

/**
 * Where ClientCapabilities are currently empty:
 */
pub struct ClientCapabilities {
    // ...
}

I noticed that hover shows the comment as

• Where ClientCapabilities are currently empty:

In looking at https://docs.rs/lsp-types/0.61.0/lsp_types/struct.ClientCapabilities.html we can see that it's rendered without the leading asterisk (or bullet in markdown).

My initial thought was that maybe we need to strip leading * off of block dock comments if present in DocCommentsOwner::doc_comment_text but that could also end up stripping markdown. Maybe it should be done in format_docs instead when we look for markdown... but by then we've lost all knowledge of the comment except for it's string contents.

[lnicola]

Triage: this still happens.

[patowen]

This was a bug in Rust nightly itself at some point as well (rust-lang/rust#92872). Since this comment type is shorthand for the #[doc="..."] attribute, would it make sense to extract the string from that attribute instead? I assume we don't need any more information about how the comment was written for the help text on mouse hover.

[Veykril]

Relevant code is here

rust-analyzer/crates/hir-def/src/attr.rs

Lines 208 to 233 in 9814d79

	pub fn docs(&self) -> Option<Documentation> {
	let docs = self.by_key("doc").attrs().filter_map(|attr| attr.string_value());
	let indent = doc_indent(self);
	let mut buf = String::new();
	for doc in docs {
	// str::lines doesn't yield anything for the empty string
	if !doc.is_empty() {
	buf.extend(Itertools::intersperse(
	doc.lines().map(|line| {
	line.char_indices()
	.nth(indent)
	.map_or(line, |(offset, _)| &line[offset..])
	.trim_end()
	}),
	"\n",
	));
	}
	buf.push('\n');
	}
	buf.pop();
	if buf.is_empty() {
	None
	} else {
	Some(Documentation(buf))
	}
	}

and here (though this we might be able to skip out on)

rust-analyzer/crates/hir-def/src/attr.rs

Lines 449 to 492 in 9814d79

	pub fn docs_with_rangemap(
	&self,
	db: &dyn DefDatabase,
	) -> Option<(Documentation, DocsRangeMap)> {
	let docs =
	self.by_key("doc").attrs().filter_map(|attr| attr.string_value().map(|s| (s, attr.id)));
	let indent = doc_indent(self);
	let mut buf = String::new();
	let mut mapping = Vec::new();
	for (doc, idx) in docs {
	if !doc.is_empty() {
	let mut base_offset = 0;
	for raw_line in doc.split('\n') {
	let line = raw_line.trim_end();
	let line_len = line.len();
	let (offset, line) = match line.char_indices().nth(indent) {
	Some((offset, _)) => (offset, &line[offset..]),
	None => (0, line),
	};
	let buf_offset = buf.len();
	buf.push_str(line);
	mapping.push((
	TextRange::new(buf_offset.try_into().ok()?, buf.len().try_into().ok()?),
	idx,
	TextRange::at(
	(base_offset + offset).try_into().ok()?,
	line_len.try_into().ok()?,
	),
	));
	buf.push('\n');
	base_offset += raw_line.len() + 1;
	}
	} else {
	buf.push('\n');
	}
	}
	buf.pop();
	if buf.is_empty() {
	None
	} else {
	Some((Documentation(buf), DocsRangeMap { mapping, source_map: self.source_map(db) }))
	}
	}
	}