Add lint for pub fns returning a Result without documenting errors

The Rust Book recommends that functions that return a `Result` type have
a doc comment with an `# Errors` section describing the kind of errors
that can be returned
(https://doc.rust-lang.org/book/ch14-02-publishing-to-crates-io.html#commonly-used-sections).
This change adds a lint to enforce this. The lint is allow by default;
it can be enabled with `#![warn(clippy::missing_errors_doc)]`.

Closes #4854.

tests/ui/doc_errors.rs

@@ -0,0 +1,64 @@
+#![warn(clippy::missing_errors_doc)]
+
+use std::io;
+
+pub fn pub_fn_missing_errors_header() -> Result<(), ()> {
+    unimplemented!();
+}
+
+/// This is not sufficiently documented.
+pub fn pub_fn_returning_io_result() -> io::Result<()> {
+    unimplemented!();
+}
+
+/// # Errors
+/// A description of the errors goes here.
+pub fn pub_fn_with_errors_header() -> Result<(), ()> {
+    unimplemented!();
+}
+
+/// This function doesn't require the documentation because it is private
+fn priv_fn_missing_errors_header() -> Result<(), ()> {
+    unimplemented!();
+}
+
+pub struct Struct1;
+
+impl Struct1 {
+    /// This is not sufficiently documented.
+    pub fn pub_method_missing_errors_header() -> Result<(), ()> {
+        unimplemented!();
+    }
+
+    /// # Errors
+    /// A description of the errors goes here.
+    pub fn pub_method_with_errors_header() -> Result<(), ()> {
+        unimplemented!();
+    }
+
+    /// This function doesn't require the documentation because it is private.
+    fn priv_method_missing_errors_header() -> Result<(), ()> {
+        unimplemented!();
+    }
+}
+
+pub trait Trait1 {
+    /// This is not sufficiently documented.
+    fn trait_method_missing_errors_header() -> Result<(), ()>;
+
+    /// # Errors
+    /// A description of the errors goes here.
+    fn trait_method_with_errors_header() -> Result<(), ()>;
+}
+
+impl Trait1 for Struct1 {
+    fn trait_method_missing_errors_header() -> Result<(), ()> {
+        unimplemented!();
+    }
+
+    fn trait_method_with_errors_header() -> Result<(), ()> {
+        unimplemented!();
+    }
+}
+
+fn main() {}