Eli Zaretskii <eliz@gnu.org> writes:

> I have a problem with the documentation of the functions and commands
> we had before, which can now be overridden by the new
> fill-region-as-paragraph-function.  The documentation was basically
> left unaltered as to what filling does, with just a single sentence,
> at the end of a very long doc string, saying that
> fill-region-as-paragraph-function could change the behavior.  But the
> truth is that such a function can completely change the result and
> invalidate the description in the doc string; in particular, the
> function which implements semantic line-feeds does exactly that.
>
> So at the very least, the doc strings should:
>
>  . mention the fill-region-as-paragraph-function early on
>  . say that the rest of the description is about the default function,
>    mentioning its symbol
>
> I also think some minimal addition to the user manual is in order, to
> the effect that the manual describes the default filling style, while
> the major mode or the user could change it via
> fill-region-as-paragraph-function.

Please, find attached a new version of the patch with the following
changes:

- In the user manual, I added a reference to
  `fill-region-as-paragraph-function'.  I also made explicit that the
  `fill-region-as-paragraph' behavior described by the manual
  corresponds to the default implementation.
- In the Emacs Lisp reference, I made explicit that the behavior
  described for `fill-region-as-paragraph' corresponds to the default
  implementation.
- Moved the original docstring of `fill-region-as-paragraph' to
  `fill-region-as-paragraph-default' given that it describes its
  specific behavior.
- I used the docstring of `fill-region-as-paragraph' to describe the
  general purpose of the command and the expected arguments.  I also
  moved the mention to `fill-region-as-paragraph-function' to the
  beginning of the docstring.
- I noticed that, after my previous patches, `fill-region-as-paragraph'
  was not a command anymore.  Now it is a command again.

        Roi