Re: emacs-lisp-docstring-fill-column: Why?

[Kevin Rodgers]

Drew Adams wrote:
>         Why does this variable exist? Doesn't buffer-local variable
>         fill-column do everything that is needed?
>
>     It fails to distinguish between comments and doc strings.
>
> So, maybe say that in the doc? As I pointed out, this variable is not even
> mentioned in the doc.
>
> Users will be confused when they find that changing the fill-column no
> longer has any effect on filling doc strings - and they will have no easy
> way to find out what is going on. I kept changing the fill column a few
> times, thinking I must have done it wrong.

M-q is bound to fill-paragraph, whose doc string references
fill-paragraph-function, whose value in Emacs Lisp mode is
lisp-fill-paragraph, whose doc string indeed does not mention
emacs-lisp-docstring-fill-column.  But its source code has this
comment:

      ;; The `fill-column' is temporarily bound to
      ;; `emacs-lisp-docstring-fill-column' if that value is an integer.

I think the doc string for lisp-fill-paragraph should have something
like this added to it:

"If the current line is within a docstring, temporarily bind
`paragraph-start' and `paragraph-separate' to recognize docstring
paragraphs, and temporarily bind `fill-column' to the value of
`emacs-lisp-docstring-fill-column' if it is an integer."

BTW, is "doc string" or "docstring" preferred?  The Emacs Lisp manual
is not consistent.

> Worse, they may think that they have successfully set the fill column for
> doc strings by setting fill-column, so they may think that doc strings are
> being filled to the column they defined, only to discover this gotcha much
> later. IOW, they might do C-u C-x f 68 (or 62), and proceed merrily to use
> M-q, without noticing that their fill-column change had no effect on the doc
> strings.

--
Kevin