--- a/xpcom/base/nscore.h
+++ b/xpcom/base/nscore.h
@@ -166,16 +166,21 @@
 #define MOZ_FORMAT_PRINTF(stringIndex, firstToCheck)  \
     __attribute__ ((format (printf, stringIndex, firstToCheck)))
 #else
 #define MOZ_FORMAT_PRINTF(stringIndex, firstToCheck)
 #endif
 
 /**
  * Generic API modifiers which return the standard XPCOM nsresult type
+ *
+ * - NS_IMETHOD: use for in-class declarations and definitions.
+ * - NS_IMETHODIMP: use for out-of-class definitions.
+ * - NS_METHOD: usually used in conjunction with NS_CALLBACK.
+ * - NS_CALLBACK: used in some legacy situations. Best avoided.
  */
 #define NS_IMETHOD          NS_IMETHOD_(nsresult)
 #define NS_IMETHODIMP       NS_IMETHODIMP_(nsresult)
 #define NS_METHOD           NS_METHOD_(nsresult)
 #define NS_CALLBACK(_name)  NS_CALLBACK_(nsresult, _name)
 
 /**
  * Import/Export macros for XPCOM APIs