How to properly document that a feature is new

[Artur Malabarba <bruce.connor.am@gmail.com>]

Right now, a mode that derives from `tabulated-list-mode' must call
`tabulated-list-init-header'.
I'd like to push the patch below, which makes it so that this is not
mandatory (if a mode doesn't call this function, it won't get a
header, but no errors will be thrown).

The problem is, if I just document (on the docstring and on the
manual) that this function is optional, a new developer who reads the
new manual won't know that it wasn't optional before. When they derive
this mode, they'll expect their package to work on Emacs 24.1-5, but
it won't.

I'm going to document this new feature in the docstring and the manual.
My question is: where do I specifically document the fact that this is
new to 25.1?
Docstring, manual, both, or neither?

Thanks,
Artur

Subject: [PATCH] * lisp/emacs-lisp/tabulated-list.el: Don't error on nil
 header-string

(tabulated-list-init-header): Document new behavior.
(tabulated-list-print-fake-header): No nothing if
`tabulated-list--header-string' is nil.
(tabulated-list--header-string): Add a docstring.

* doc/lispref/modes.texi (Tabulated List Mode): Document it.
---
 doc/lispref/modes.texi            |  6 +++---
 lisp/emacs-lisp/tabulated-list.el | 31 ++++++++++++++++++++-----------
 2 files changed, 23 insertions(+), 14 deletions(-)

diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 8cb0f3d..c325506 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -958,9 +958,9 @@ Menu,,, emacs, The GNU Emacs Manual}).
 way, specifying @code{tabulated-list-mode} as the second argument
 (@pxref{Derived Modes}).  The body of the @code{define-derived-mode}
 form should specify the format of the tabulated data, by assigning
-values to the variables documented below; then, it should call the
-function @code{tabulated-list-init-header} to initialize the header
-line.
+values to the variables documented below; optionally, it can then call
+the function @code{tabulated-list-init-header}, which will populate a
+header with the names of the columns.

   The derived mode should also define a @dfn{listing command}.  This,
 not the mode command, is what the user calls (e.g., @kbd{M-x
diff --git a/lisp/emacs-lisp/tabulated-list.el
b/lisp/emacs-lisp/tabulated-list.el
index b12edc8..7eaddc7 100644
--- a/lisp/emacs-lisp/tabulated-list.el
+++ b/lisp/emacs-lisp/tabulated-list.el
@@ -179,11 +179,18 @@ If ADVANCE is non-nil, move forward by one line
afterwards."
     table)
   "The `glyphless-char-display' table in Tabulated List buffers.")

-(defvar tabulated-list--header-string nil)
+(defvar tabulated-list--header-string nil
+  "Holds the header if `tabulated-list-use-header-line' is nil.
+Populated by `tabulated-list-init-header'.")
 (defvar tabulated-list--header-overlay nil)

 (defun tabulated-list-init-header ()
-  "Set up header line for the Tabulated List buffer."
+  "Set up header line for the Tabulated List buffer.
+Up to Emacs 24.5, any major-mode which derives
+`tabulated-list-mode' must call this function.
+
+As of Emacs 25.1 it is safe for a mode to not call this function,
+in which case it will have no header."
   ;; FIXME: Should share code with tabulated-list-print-col!
   (let ((x (max tabulated-list-padding 0))
     (button-props `(help-echo "Click to sort by column"
@@ -243,15 +250,17 @@ If ADVANCE is non-nil, move forward by one line
afterwards."
       (setq-local tabulated-list--header-string cols))))

 (defun tabulated-list-print-fake-header ()
-  "Insert a fake Tabulated List \"header line\" at the start of the buffer."
-  (goto-char (point-min))
-  (let ((inhibit-read-only t))
-    (insert tabulated-list--header-string "\n")
-    (if tabulated-list--header-overlay
-    (move-overlay tabulated-list--header-overlay (point-min) (point))
-      (setq-local tabulated-list--header-overlay
-                  (make-overlay (point-min) (point))))
-    (overlay-put tabulated-list--header-overlay 'face 'underline)))
+  "Insert a fake Tabulated List \"header line\" at the start of the buffer.
+Do nothing if `tabulated-list--header-string' is nil."
+  (when tabulated-list--header-string
+    (goto-char (point-min))
+    (let ((inhibit-read-only t))
+      (insert tabulated-list--header-string "\n")
+      (if tabulated-list--header-overlay
+          (move-overlay tabulated-list--header-overlay (point-min) (point))
+        (setq-local tabulated-list--header-overlay
+                    (make-overlay (point-min) (point))))
+      (overlay-put tabulated-list--header-overlay 'face 'underline))))

 (defun tabulated-list-revert (&rest ignored)
   "The `revert-buffer-function' for `tabulated-list-mode'.
-- 
2.3.7