From 822bde072b953be5a1a48fbf9f43523a76d69f05 Mon Sep 17 00:00:00 2001
From: Christian Meusel <christian.meusel@posteo.de>
Date: Wed, 22 May 2024 22:02:11 +0200
Subject: [PATCH] Point out issue with failing builds due to syntax errors

This is a trap "for young players" and loosing feedback from rustc or
your favorite code analysis tools won't make things better. Let's point
out the issue and the solution given in issue #472 upfront.
---
 docs.md | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/docs.md b/docs.md
index e5347bf36..c8ce9f4f2 100644
--- a/docs.md
+++ b/docs.md
@@ -68,6 +68,23 @@ fn main() {
 
 You can add configuration options using the [`Builder`](https://docs.rs/cbindgen/*/cbindgen/struct.Builder.html#methods) interface.
 
+When actively working on code, you likely don't want cbindgen to fail the entire build. Instead of expect-ing the result of the header generation, you could [ignore parse errors](https://github.com/mozilla/cbindgen/issues/472#issuecomment-831439826) and let rustc or your code analysis bring up:
+
+```rust
+    // ...
+    .generate()
+    .map_or_else(
+        |error| match error {
+            cbindgen::Error::ParseSyntaxError { .. } => {}
+            e => panic!("{:?}", e),
+        },
+        |bindings| {
+            bindings.write_to_file("target/include/bindings.h");
+        },
+    );
+}
+```
+
 Be sure to add the following section to your Cargo.toml:
 
 ```