parser: Introduce cbindgen:ignore comment annotation, to allow ignoring items or modules.

docs.md

@@ -235,6 +235,19 @@ An annotation may be a bool, string (no quotes), or list of strings. If just the
 
 Most annotations are just local overrides for identical settings in the cbindgen.toml, but a few are unique because they don't make sense in a global context. The set of supported annotation are as follows:
 
+### Ignore annotation
+
+cbindgen will automatically ignore any `#[test]` or `#[cfg(test)]` item it
+finds. You can manually ignore other stuff with the `ignore` annotation
+attribute:
+
+```rust
+pub mod my_interesting_mod;
+
+/// cbindgen:ignore
+pub mod my_uninteresting_mod; // This won't be scanned by cbindgen.
+```
+
 ### Struct Annotations
 
 * field-names=\[field1, field2, ...\] -- sets the names of all the fields in the output struct. These names will be output verbatim, and are not eligible for renaming.
@@ -335,7 +348,6 @@ Given configuration in the cbindgen.toml, `cbindgen` can generate these attribut
 
 This is controlled by the `swift_name_macro` option in the cbindgen.toml.
 
-
 ## cbindgen.toml
 
 Most configuration happens through your cbindgen.toml file. Every value has a default (that is usually reasonable), so you can start with an empty cbindgen.toml and tweak it until you like the output you're getting.

src/bindgen/utilities.rs

@@ -71,26 +71,40 @@ impl SynItemFnHelpers for syn::ImplItemMethod {
     }
 }
 
+/// Returns whether this attribute causes us to skip at item. This basically
+/// checks for `#[cfg(test)]`, `#[test]`, `/// cbindgen::ignore` and
+/// variations thereof.
 fn is_skip_item_attr(attr: &syn::Meta) -> bool {
     match *attr {
         syn::Meta::Path(ref path) => {
-            if path.is_ident("test") {
-                return true;
-            }
+            // TODO(emilio): It'd be great if rustc allowed us to use a syntax
+            // like `#[cbindgen::ignore]` or such.
+            path.is_ident("test")
         }
         syn::Meta::List(ref list) => {
-            if list.path.is_ident("cfg") {
-                return list.nested.iter().any(|nested| match *nested {
-                    syn::NestedMeta::Meta(ref meta) => {
-                        return is_skip_item_attr(meta);
-                    }
-                    syn::NestedMeta::Lit(..) => false,
-                });
+            if !list.path.is_ident("cfg") {
+                return false;
             }
+            list.nested.iter().any(|nested| match *nested {
+                syn::NestedMeta::Meta(ref meta) => {
+                    return is_skip_item_attr(meta);
+                }
+                syn::NestedMeta::Lit(..) => false,
+            })
+        }
+        syn::Meta::NameValue(ref name_value) => {
+            if name_value.path.is_ident("doc") {
+                if let syn::Lit::Str(ref content) = name_value.lit {
+                    // FIXME(emilio): Maybe should use the general annotation
+                    // mechanism, but it seems overkill for this.
+                    if content.value().trim() == "cbindgen:ignore" {
+                        return true;
+                    }
+                }
+            }
+            false
         }
-        syn::Meta::NameValue(..) => {}
     }
-    false
 }
 
 pub trait SynAttributeHelpers {

tests/expectations/both/ignore.c

@@ -0,0 +1,6 @@
+#include <stdarg.h>
+#include <stdbool.h>
+#include <stdint.h>
+#include <stdlib.h>
+
+void no_ignore_root(void);

tests/expectations/both/ignore.compat.c

@@ -0,0 +1,14 @@
+#include <stdarg.h>
+#include <stdbool.h>
+#include <stdint.h>
+#include <stdlib.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif // __cplusplus
+
+void no_ignore_root(void);
+
+#ifdef __cplusplus
+} // extern "C"
+#endif // __cplusplus

tests/expectations/ignore.c

@@ -0,0 +1,6 @@
+#include <stdarg.h>
+#include <stdbool.h>
+#include <stdint.h>
+#include <stdlib.h>
+
+void no_ignore_root(void);

tests/expectations/ignore.compat.c

@@ -0,0 +1,14 @@
+#include <stdarg.h>
+#include <stdbool.h>
+#include <stdint.h>
+#include <stdlib.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif // __cplusplus
+
+void no_ignore_root(void);
+
+#ifdef __cplusplus
+} // extern "C"
+#endif // __cplusplus

tests/expectations/ignore.cpp

@@ -0,0 +1,10 @@
+#include <cstdarg>
+#include <cstdint>
+#include <cstdlib>
+#include <new>
+
+extern "C" {
+
+void no_ignore_root();
+
+} // extern "C"

tests/expectations/tag/ignore.c

@@ -0,0 +1,6 @@
+#include <stdarg.h>
+#include <stdbool.h>
+#include <stdint.h>
+#include <stdlib.h>
+
+void no_ignore_root(void);

tests/expectations/tag/ignore.compat.c

@@ -0,0 +1,14 @@
+#include <stdarg.h>
+#include <stdbool.h>
+#include <stdint.h>
+#include <stdlib.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif // __cplusplus
+
+void no_ignore_root(void);
+
+#ifdef __cplusplus
+} // extern "C"
+#endif // __cplusplus

tests/rust/ignore.rs

@@ -0,0 +1,12 @@
+/// cbindgen:ignore
+#[no_mangle]
+pub extern "C" fn root() {}
+
+/// cbindgen:ignore
+///
+/// Something else.
+#[no_mangle]
+pub extern "C" fn another_root() {}
+
+#[no_mangle]
+pub extern "C" fn no_ignore_root() {}