1294338 - charCodeAt and codePointAt in String documentation seem almost backwards

Status: RESOLVED WONTFIX

(Developer Documentation Graveyard :: JavaScript, defect, P5)

Description

[lee.justin.m]

:: Developer Documentation Request

      Request Type: Correction
     Gecko Version: unspecified
 Technical Contact: 

:: Details

The documentation for charCodeAt() and codePointAt() seems backwards in a couple of places.  Currently, the "Methods" section of the String object reads as follows:

String.prototype.charCodeAt()
Returns a number indicating the Unicode value of the character at the given index.

String.prototype.codePointAt()
Returns a non-negative integer that is the UTF-16 encoded code point value at the given position.

When I first read this, it almost seemed like the descriptions are completely backwards.  charCodeAt() returns a number representing the UTF-16 code unit at the given index.  codePointAt() returns the Unicode code point value at the given index (saying that it is a "UTF-16 encoded code point value" is confusing given that code points are independent of encoding).

This gets more confusing when you click through to the charCodeAt() documentation, which includes a "fixedCharCodeAt" function.  This is totally bizarre, because, as far as I can tell, what "fixedCharCodeAt" does is return the code point, not the code unit.  By including this function, the documentation really through me for a loop (I was already confused by the summaries), because it suggests that the "correct" answer for charCodeAt() is to return a code unit.  But, again, that's backwards. 

I'd suggest for clarity that the method summaries be changed to:

String.prototype.charCodeAt()
Returns a number indicating the Unicode value of the UTF-16 code unit at the given position.

String.prototype.codePointAt()
Returns a number indicating the code point value at the given position, or, if no UTF-16 surrogate par begins at the given position, returns the code unit at that position.

I'd also suggest moving "fixedCharCodeAt" to the codePointAt() docs with appropriate modifications.  (Same with knownCharCodeAt, which has the same problem).

Comment 1

[BMO Automation]

MDN Web Docs' bug reporting has now moved to GitHub. From now on, please file content bugs at https://github.com/mdn/sprints/issues/ and platform bugs at https://github.com/mdn/kuma/issues/.