RE: Leading * in docstrings of defcustoms.

["Drew Adams" <drew.adams@oracle.com>]

> They should already be omitted, or strongly deprecated, in 
> the manuals. For example, the Variable Definitions node in
> the Lisp manual says
> 
>   There is no need to start [the docstring] with a `*', because
>   `defcustom' automatically marks `option' as a "user option"
> 
> If you find a spot in the manual that still follows the old 
> convention, please let us know.

Elisp manual nodes:

* Defining Variables

  If the variable is a user option that users would want to set
  interactively, you should use `*' as the first character of
                 ^^^^^^^^^^^^^^^^^^
  DOC-STRING.  This lets users set the variable conveniently using
  the `set-variable' command.  Note that you should nearly always
  use `defcustom' instead of `defvar' to define these variables, so
  that users can use `M-x customize' and related commands to set
  them.  *Note Customization::.

  ...

  User option variables are distinguished from other variables either
  though being declared using `defcustom'(1) or by the first
  character of their `variable-documentation' property.  If the
  property exists and is a string, and its first character is `*',
  then the variable is a user option.  Aliases of user options are
  also user options.

While this "if" is true, and nothing here claims the "only if" case, it's easy
to misread that text to also think the "only if" case applies, that is, that if
a symbol has property `variable-documentation' then `*' is _required_ for a
variable to be a user option.

* Accessing Documentation

  goal-column     Option
  *Semipermanent goal column for vertical motion, as set by ...

  The asterisk `*' as the first character of a variable's doc string,
  as shown above for the `goal-column' variable, means that it is a user
  option; see the description of `defvar' in *Note Defining Variables::.

Again, depending on what is understood by "means", one can read this as saying
that `*' is necessary if you want the variable to be a user option. Especially
considering that `goal-column' is a defcustom, this text should perhaps be
removed or updated.