Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> Since I started Elisp programming, I've always wondered why there is
>> an opposition between the following lines of the manual:
>
>>  -- Macro: defcustom option standard doc [keyword value]...
>>      [...]There is no need to start [the docstring] with a `*'
>
>> [and]
>> (this is 3011 matches of bad-style according to the doc)
>
>> Is there any reason ?
>
> History.  The * used to be necessary for M-x set-variable to be usable.
> Now the * in defcustoms is just a relic and should slowly disappear.

Why slowly? :-) Don't you think it can be disturbing for new users to
see that star, and after a little search on the (info "(emacs)") to
read:
     (it is an obsolete indicator that may eventually disappear.)

And, reading that part of the manual, there is:

  The line that says you can customize the variable indicates that
  this variable is a user option.

So the only documentation for `user options' is that some of them are
customizable variable.  Don't we want to talk about (defvar)s with
a docstring starting by "*"?  Won't the user be surprised to see that
the completion list for M-x set-variable and M-x customize-variable
aren't the same?

Apart from that, why don't we propose in C-h v to modify user
variables ((defvar)s with "*")?  I propose the following change, if
the idea is ok.