[Webkit-unassigned] [Bug 114240] Hopefully helpful comments for some String methods

[bugzilla-daemon at webkit.org]

https://bugs.webkit.org/show_bug.cgi?id=114240





--- Comment #7 from Benjamin Poulain <benjamin at webkit.org>  2013-04-09 21:28:32 PST ---
(In reply to comment #6)
> Benjamin: proper usage documentation would be awesome! At the same time, would you agree that this is a (tiny) step in the right direction?

No, not really.

Take this:
    // Make sure the String is8Bit() before calling this.
    const LChar* characters8() const

This is not strictly true. If you juste created a string with ASCIILiteral (or another 8bits constructor), you can call this method safely.

Or this:
    // This is expensive for 8-bit strings.
    //
    // Write two branches of the code using characters8() and characters16(),
    // and use is8Bit() to branch. If the String can be null, use isNull() or
    // isEmpty() to handle that special case.

This is explaining a particular pattern. It is also not strictly true that this method is expensive. If there is already a 16bits shadow, this is still pretty fast.

Instead, if the reader knew what a WTF::String is, you should just be able to write:
    // Return a 16 bits representation of the string. If the string is 8 bits, the method
    // will upconvert the caracters.


Comments should provide comprehension for the concepts. The information about details is already in the code, it does not need to be repeated.

-- 
Configure bugmail: https://bugs.webkit.org/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are the assignee for the bug.