diff --git a/layout/style/nsCSSProps.h b/layout/style/nsCSSProps.h
index 7fa6e19717ca..fe3e19892b46 100644
--- a/layout/style/nsCSSProps.h
+++ b/layout/style/nsCSSProps.h
@@ -97,13 +97,22 @@
 // Define what mechanism the CSS parser uses for parsing the property.
 // See CSSParserImpl::ParseProperty(nsCSSProperty).  Don't use 0 so that
 // we can verify that every property sets one of the values.
+//
+// CSS_PROPERTY_PARSE_FUNCTION must be used for shorthand properties,
+// since it's the only mechanism that allows appending values for
+// separate properties.  Longhand properties that require custom parsing
+// functions should prefer using CSS_PROPERTY_PARSE_VALUE (or
+// CSS_PROPERTY_PARSE_VALUE_LIST) and
+// CSS_PROPERTY_VALUE_PARSER_FUNCTION, though a number of existing
+// longhand properties use CSS_PROPERTY_PARSE_FUNCTION instead.
 #define CSS_PROPERTY_PARSE_PROPERTY_MASK          (7<<9)
 #define CSS_PROPERTY_PARSE_INACCESSIBLE           (1<<9)
 #define CSS_PROPERTY_PARSE_FUNCTION               (2<<9)
 #define CSS_PROPERTY_PARSE_VALUE                  (3<<9)
 #define CSS_PROPERTY_PARSE_VALUE_LIST             (4<<9)
 
-// See CSSParserImpl::ParseSingleValueProperty
+// See CSSParserImpl::ParseSingleValueProperty and comment above
+// CSS_PROPERTY_PARSE_FUNCTION (which is different).
 #define CSS_PROPERTY_VALUE_PARSER_FUNCTION        (1<<12)
 MOZ_STATIC_ASSERT((CSS_PROPERTY_PARSE_PROPERTY_MASK &
                    CSS_PROPERTY_VALUE_PARSER_FUNCTION) == 0,