[dif] Add a comment explaining how to drop an error on the ground
See https://gcc.gnu.org/bugzilla/show_bug.cgi?id=25509, which
necessitates doing this in a non-standard, but still portable, manner.
Signed-off-by: Miguel Young de la Sota <mcyoung@google.com>
diff --git a/sw/device/lib/dif/dif_warn_unused_result.h b/sw/device/lib/dif/dif_warn_unused_result.h
index 315f243..fa4225d 100644
--- a/sw/device/lib/dif/dif_warn_unused_result.h
+++ b/sw/device/lib/dif/dif_warn_unused_result.h
@@ -21,6 +21,13 @@
* This attribute must be used to mark all DIFs which return an error value of
* some kind, to ensure that callers do not accidentally drop the error on the
* ground.
+ *
+ * Normally, the standard way to drop such a value on the ground explicitly is
+ * with the syntax `(void)expr;`, in analogy with the behavior of C++'s
+ * `[[nodiscard]]` attribute.
+ * However, GCC does not implement this, so the idiom `if (expr) {}` should be
+ * used instead, for the time being.
+ * See https://gcc.gnu.org/bugzilla/show_bug.cgi?id=25509.
*/
#define DIF_WARN_UNUSED_RESULT __attribute__((warn_unused_result))
