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