new lints around #[must_use] fns

`must_use_unit` lints unit-returning functions with a `#[must_use]`
attribute, suggesting to remove it.

`double_must_use` lints functions with a plain `#[must_use]`
attribute, but which return a type which is already `#[must_use]`,
so the attribute has no benefit.

`must_use_candidate` is a pedantic lint that lints functions and
methods that return some non-unit type that is not already
`#[must_use]` and suggests to add the annotation.

clippy_lints/src/doc.rs

@@ -191,6 +191,7 @@ impl<'a, 'tcx> LateLintPass<'a, 'tcx> for DocMarkdown {
 /// need to keep track of
 /// the spans but this function is inspired from the later.
 #[allow(clippy::cast_possible_truncation)]
+#[must_use]
 pub fn strip_doc_comment_decoration(comment: &str, span: Span) -> (String, Vec<(usize, Span)>) {
     // one-line comments lose their prefix
     const ONELINERS: &[&str] = &["///!", "///", "//!", "//"];