diff --git a/src/lib.rs b/src/lib.rs
index df5b129200..3eda6af9be 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -712,14 +712,21 @@ impl Builder {
         self
     }
 
-    /// Whether the generated bindings should contain documentation comments or
-    /// not.
+    /// Whether the generated bindings should contain documentation comments
+    /// (docstrings) or not.
     ///
     /// This ideally will always be true, but it may need to be false until we
     /// implement some processing on comments to work around issues as described
-    /// in:
+    /// in [rust-bindgen issue
+    /// #426](https://github.com/rust-lang/rust-bindgen/issues/426).
     ///
-    /// https://github.com/rust-lang/rust-bindgen/issues/426
+    /// Note that clang by default excludes comments from system headers, pass
+    /// `-fretain-comments-from-system-headers` as
+    /// [`clang_arg`][Builder::clang_arg] to include them. It can also be told
+    /// to process all comments (not just documentation ones) using the
+    /// `-fparse-all-comments` flag. See [slides on clang comment parsing](
+    /// https://llvm.org/devmtg/2012-11/Gribenko_CommentParsing.pdf) for
+    /// background and examples.
     pub fn generate_comments(mut self, doit: bool) -> Self {
         self.options.generate_comments = doit;
         self