bug#6958: Documentation: `posn-actual-col-row' is unclear

[MON KEY]

documentation of `posn-actual-col-row' is unclear.

,---- (documentation 'posn-actual-col-row)
|
| Return the actual column and row in position, measured in characters.
| These are the actual row number in the window and character number
in that row.
| Return nil if position does not contain the actual position; in that case
| `posn-col-row' can be used to get approximate values.
| position should be a list of the form returned by the `event-start'
| and `event-end' functions.
|
`----

How is a position, "measured in characters."?
What is a, "character number in that row"?

Is this equivalent to the return value of `char-to-string'?

(char-to-string
 (car
  (posn-col-row
   (posn-at-point
    (window-point (selected-window) ) (selected-window)))))
;=> ";"

At the very least the following portion of doc is poorly phrased:
"These are the actual row number in the window and character number in
that row."
 ^^^^^^^^^

Should be something more like,
"This is the actual row number in the window and character number in that row."
 ^^^^^^^

However, even then the above definition is tautological:
 ME: "What is `posn-actual-col-row'?"
 DOC: "... the actual row number ..."

Also, there is no mention of which list element of the list returned
by the `event-start' this procedure is an accessor of e.g.:
 POS (COL . ROW)

Likewise, there is no indication of the order of the return value is a
cons of the form:
 (COLUMN . ROW)

--
/s_P\