bug#6576: documentation `string-to-char' is incorrect

[Eli Zaretskii <eliz@gnu.org>]

> From: Andreas Schwab <schwab@linux-m68k.org>
> Cc: MON KEY <monkey@sandpframing.com>,  6576@debbugs.gnu.org
> Date: Wed, 07 Jul 2010 10:40:00 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >   "Return the Unicode codepoint of the first character of STRING.
> 
> This is not correct.  The value is just the internal encoding of the
> character.

Which is Unicode, AFAIK.  The note takes care of the extension that
is specific to Emacs.  If there are other extensions that I forgot, we
can add more notes.

> It's identical to (aref STRING 0)

I don't think talking about `(aref STRING 0)' in a doc string is a
good idea.  Only people who know quite a lot about the internal
representation and what aref does in this case will understand such a
documentation.

> except that it returns 0 for the empty string

This fact should probably be mentioned in the doc string.

> >   Note: eight-bit characters are returned as single-byte values in the
> >   range 160 to 255, inclusive."
> 
> That depends on the multibyteness of the string.

Eight-bit characters are defined as such only in multibyte strings.

But I think the note is correct for unibyte strings as well, because
they by definition include raw bytes.