Bug 1325541 - Expand comments for MOZ_MUST_USE. r=froydnj.
authorNicholas Nethercote <nnethercote@mozilla.com>
Fri, 23 Dec 2016 16:11:33 +1100
changeset 328497 4864d0c2b1bc50d688db5703b9ae7dabb55d2679
parent 328496 18151dec259d835de31c4750d278d218b5da783e
child 328498 f99d55d2dc137b3b8f63192d2d65c20bf7c83bd9
push id31175
push usercbook@mozilla.com
push dateMon, 09 Jan 2017 09:33:22 +0000
treeherdermozilla-central@701868bfddcb [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersfroydnj
bugs1325541
milestone53.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1325541 - Expand comments for MOZ_MUST_USE. r=froydnj. DONTBUILD because it's a comment-only change.
mfbt/Attributes.h
--- a/mfbt/Attributes.h
+++ b/mfbt/Attributes.h
@@ -240,20 +240,38 @@
 /**
  * MOZ_MUST_USE tells the compiler to emit a warning if a function's
  * return value is not used by the caller.
  *
  * Place this attribute at the very beginning of a function declaration. For
  * example, write
  *
  *   MOZ_MUST_USE int foo();
+ * or
+ *   MOZ_MUST_USE int foo() { return 42; }
  *
- * or
+ * MOZ_MUST_USE is most appropriate for functions where the return value is
+ * some kind of success/failure indicator -- often |nsresult|, |bool| or |int|
+ * -- because these functions are most commonly the ones that have missing
+ * checks. There are three cases of note.
+ *
+ * - Fallible functions whose return values should always be checked. For
+ *   example, a function that opens a file should always be checked because any
+ *   subsequent operations on the file will fail if opening it fails. Such
+ *   functions should be given a MOZ_MUST_USE annotation.
  *
- *   MOZ_MUST_USE int foo() { return 42; }
+ * - Fallible functions whose return value need not always be checked. For
+ *   example, a function that closes a file might not be checked because it's
+ *   common that no further operations would be performed on the file. Such
+ *   functions do not need a MOZ_MUST_USE annotation.
+ *
+ * - Infallible functions, i.e. ones that always return a value indicating
+ *   success. These do not need a MOZ_MUST_USE annotation. Ideally, they would
+ *   be converted to not return a success/failure indicator, though sometimes
+ *   interface constraints prevent this.
  */
 #if defined(__GNUC__) || defined(__clang__)
 #  define MOZ_MUST_USE __attribute__ ((warn_unused_result))
 #else
 #  define MOZ_MUST_USE
 #endif
 
 /**