bug#24979: 24.5; Doc string of `current-word'

[Eli Zaretskii <eliz@gnu.org>]

> Date: Mon, 21 Nov 2016 10:24:56 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> 
> This part of the doc string is wrong:
> 
>  The function, belying its name, normally finds a symbol.
> 
> 
> 1. There is no "normally".  Do you mean often?  Usually?  Sometimes?
>    (When?)

"Normally" is GNU and Emacs parlance for "by default", and is usually
(as in this case) followed by the description of the non-default use
case.  You will find gazillions of this in the documentation.

> 2. It always returns a string, never a symbol.  A symbol is a Lisp
>    object.  If you mean that it often returns a string that has symbol,
>    not word, syntax, then say so.  That does not mean that it returns a
>    symbol.  Yes, the first line of the doc now says that it returns a
>    string.  This means that the doc as a whole is currently confusing
>    and inconsistent.

I think this is splitting hair, probably because "symbol" is ambiguous
due to its being a Lisp object.  E.g., if the doc string said

  Return the word at or near point, as a string.

you wouldn't object, because "word" is not a Lisp object.

Anyway, I modified the doc string to say

    "Return the word at or near point, as a string.
  The return value includes no text properties.

  If optional arg STRICT is non-nil, return nil unless point is
  within or adjacent to a word, otherwise look for a word within
  point's line.  If there is no word anywhere on point's line, the
  value is nil regardless of STRICT.

  By default, this function treats as a single word any sequence of
  characters that have either word or symbol syntax.  If optional
  arg REALLY-WORD is non-nil, only characters of word syntax can
  constitute a word."

Thanks.