Document new treatment of 'comment-auto-fill-only-comments'

* doc/lispref/text.texi (Auto Filling): Add reference to Emacs
manual.  Add description of 'comment-auto-fill-only-comments'.
* etc/NEWS: Mention new treatment of
'comment-auto-fill-only-comments'.

doc/lispref/text.texi

@@ -1886,10 +1886,10 @@ prefix or @code{nil}, meaning it has failed to determine a prefix.
 @cindex filling, automatic
 @cindex Auto Fill mode
 
-@c FIXME: I don't think any of the variables below is a/an normal/abnormal hook.
-  Auto Fill mode is a minor mode that fills lines automatically as text
-is inserted.  This section describes the hook used by Auto Fill mode.
-For a description of functions that you can call explicitly to fill and
+Auto Fill mode is a minor mode that fills lines automatically as text is
+inserted.  @xref{Auto Fill,,, emacs, The GNU Emacs Manual}.  This
+section describes some variables used by Auto Fill mode.  For a
+description of functions that you can call explicitly to fill and
 justify existing text, see @ref{Filling}.
 
   Auto Fill mode also enables the functions that change the margins and
@@ -1898,11 +1898,11 @@ justification style to refill portions of the text.  @xref{Margins}.
 @defvar auto-fill-function
 The value of this buffer-local variable should be a function (of no
 arguments) to be called after self-inserting a character from the table
-@code{auto-fill-chars}.  It may be @code{nil}, in which case nothing
-special is done in that case.
+@code{auto-fill-chars}, see below.  It may be @code{nil}, in which case
+nothing special is done in that case.
 
-The value of @code{auto-fill-function} is @code{do-auto-fill} when
-Auto-Fill mode is enabled.  That is a function whose sole purpose is to
+The value of @code{auto-fill-function} is @code{do-auto-fill} when Auto
+Fill mode is enabled.  That is a function whose sole purpose is to
 implement the usual strategy for breaking a line.
 @end defvar
 
@@ -1919,6 +1919,14 @@ self-inserted---space and newline in most language environments.  They
 have an entry @code{t} in the table.
 @end defvar
 
+@defopt comment-auto-fill-only-comments
+This variable, if non-@code{nil}, means to fill lines automatically
+within comments only.  More precisley, this means that if a comment
+syntax was defined for the current buffer, then self-inserting a
+character outside of a comment will not call @code{auto-fill-function}.
+@end defopt
+
+
 @node Sorting
 @section Sorting Text
 @cindex sorting text

etc/NEWS

@@ -1272,6 +1272,11 @@ table implementation.  This uses a new bytecode op 'switch', which
 isn't compatible with previous Emacs versions.  This functionality can
 be disabled by setting 'byte-compile-cond-use-jump-table' to nil.
 
++++
+** If 'comment-auto-fill-only-comments' is non-nil, 'auto-fill-function'
+is now called only if either no comment syntax is defined for the
+current buffer or the self-insertion takes place within a comment.
+
 ---
 ** The alist 'ucs-names' is now a hash table.