How to properly document that a feature is new

How to properly document that a feature is new

[Artur Malabarba]

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

RE: How to properly document that a feature is new

[Drew Adams]

> My question is: where do I specifically document the fact that this
> is new to 25.1?  Docstring, manual, both, or neither?

NEWS (only).  (Well, AntiNEWS too, if that still exists.)

NEWS is the Emacs equivalent of Release Notes.  In general, only NEWS
covers release-specific stuff.

The current doc should describe the current release of Emacs.  It can
mention that XYZ started with version N.M of Emacs, if that is really
needed for some reason (e.g. security), but that should be the case
rarely, if at all.

(My opinion, not necessarily official policy.)

Re: How to properly document that a feature is new

[Eli Zaretskii]

> Date: Mon, 11 May 2015 11:12:29 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> 
> > My question is: where do I specifically document the fact that this
> > is new to 25.1?  Docstring, manual, both, or neither?
> 
> NEWS (only).  (Well, AntiNEWS too, if that still exists.)

Anti-news still exist, but they are only updated once in a major
release, and only describe the main anti-changes, never going down to
details such as this one.

Re: How to properly document that a feature is new

[Stefan Monnier]

> The current doc should describe the current release of Emacs.  It can
> mention that XYZ started with version N.M of Emacs, if that is really
> needed for some reason (e.g. security), but that should be the case
> rarely, if at all.
> (My opinion, not necessarily official policy.)

Additionally to being your opinion, it's actually the official
policy, indeed.


        Stefan