As of this writing, the comments appear like so:

    /** Retrieve int value for the element safely.  Zero returned if not a number. */
    int numberInt() const;
    /** Retrieve long value for the element safely.  Zero returned if not a number.
     *  Behavior is not defined for double values that are NaNs, or too large/small
     *  to be represented by long longs */
    long long numberLong() const;

There are a few problems with this:

1. The documentation for numberLong() elaborates about undefined behavior for NaN and large doubles, but we don't have the same documentation for numberInt().
2. While we're at it, we should be explicit that calling this on +/-infinity is also UB.
3. It's unclear what's meant by "safely" in these comments. In fact, these operations are unsafe to perform on an arbitrary BSONElement due to the possibility of undefined behavior. That's why we have a separate function called BSONElement::safeNumberLong(). I recommend that we delete the word "safely".
4. The sentence "Zero returned if not a number" is confusing, since it doesn't disambiguate between NaN and non-numeric BSON types. We should say "Zero is returned if the BSON type is non-numeric. Results in undefined behavior if the BSON type is numeric but the value is NaN, +/-Infinity, ...".