Improve documentation about regex (rust-lang#2494)

Remove repeating documentation and keep it in a single section.

Author: pvdrz

bindgen/lib.rs

@@ -262,14 +262,27 @@ impl std::fmt::Display for Formatter {
 ///
 /// # Regular expression arguments
 ///
-/// Some [`Builder`] methods like the `allowlist_*` and `blocklist_*` family of methods allow
-/// regular expressions as arguments. These regular expressions will be parenthesized and wrapped
-/// in `^` and `$`. So if `<regex>` is passed as argument, the regular expression to be stored will
-/// be `^(<regex>)$`.
+/// Some [`Builder`] methods such as the `allowlist_*` and `blocklist_*` methods allow regular
+/// expressions as arguments. These regular expressions will be enclosed in parentheses and
+/// anchored with `^` and `$`. So if the argument passed is `<regex>`, the regular expression to be
+/// stored will be `^(<regex>)$`.
+///
+/// As a consequence, regular expressions passed to `bindgen` will try to match the whole name of
+/// an item instead of a section of it, which means that to match any items with the prefix
+/// `prefix`, the `prefix.*` regular expression must be used.
+///
+/// Certain methods, like [`Builder::allowlist_function`], use regular expressions over function
+/// names. To match C++ methods, prefix the name of the type where they belong followed by an
+/// underscore. So if the type `Foo` has a method `bar`, it can be matched with the `Foo_bar`
+/// regular expression.
+///
+/// Additionally, Objective-C interfaces can be matched by prefixing the regular expression with
+/// `I`. For example, the `IFoo` regular expression matches the `Foo` interface and the `IFoo_foo`
+/// regular expression matches the `foo` method of the `Foo` interface.
 ///
 /// Releases of `bindgen` with a version lesser or equal to `0.62.0` used to accept the wildcard
 /// pattern `*` as a valid regular expression. This behavior has been deprecated and the `.*`
-/// pattern must be used instead.
+/// regular expression must be used instead.
 #[derive(Debug, Default, Clone)]
 pub struct Builder {
     options: BindgenOptions,

bindgen/options/helpers.rs

@@ -4,12 +4,9 @@ macro_rules! regex_option {
     ($(#[$attrs:meta])* pub fn $($tokens:tt)*) => {
         $(#[$attrs])*
         ///
-        /// Regular expressions are supported. To match any items that start with `prefix` use the
-        /// `"prefix.*"` regular expression.
-        ///
-        /// Check the [regular expression arguments](./struct.Builder.html#regular-expression-arguments)
-        /// section and the [regex](https://docs.rs/regex) crate documentation for further
-        /// information.
+        /// Regular expressions are supported. Check the [regular expression
+        /// arguments](./struct.Builder.html#regular-expression-arguments) section and the
+        /// [regex](https://docs.rs/regex) crate documentation for further information.
         pub fn $($tokens)*
     };
 }

bindgen/options/mod.rs

@@ -171,10 +171,6 @@ options! {
         methods: {
             regex_option! {
                 /// Do not generate any bindings for the given function.
-                ///
-                /// Methods can be blocklisted by prefixing the name of the type where they belong
-                /// followed by an underscore. So if the type `Foo` has a method `bar`, it can be
-                /// blocklisted as `Foo_bar`.
                 pub fn blocklist_function<T: AsRef<str>>(mut self, arg: T) -> Builder {
                     self.options.blocklisted_functions.insert(arg);
                     self
@@ -289,10 +285,6 @@ options! {
             regex_option! {
                 /// Generate bindings for the given function.
                 ///
-                /// Methods can be allowlisted by prefixing the name of the type where they belong
-                /// followed by an underscore. So if the type `Foo` has a method `bar`, it can be
-                /// allowlisted as `Foo_bar`.
-                ///
                 /// This option is transitive by default. Check the documentation of the
                 /// [`Builder::allowlist_recursively`] method for further information.
                 pub fn allowlist_function<T: AsRef<str>>(mut self, arg: T) -> Builder {
@@ -418,7 +410,7 @@ options! {
             regex_option! {
                 /// Mark the given `enum` as a Rust `enum`.
                 ///
-                /// This means that each variant of the `enum` will be represented as a Rust `enum
+                /// This means that each variant of the `enum` will be represented as a Rust `enum`
                 /// variant.
                 ///
                 /// **Use this with caution**, creating an instance of a Rust `enum` with an