bug#21074: [PATCH] Add docs for two tabulated-list functions

[Alex Branham <alex.branham@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 2931 bytes --]


On Sat 02 Feb 2019 at 10:33, Eli Zaretskii <eliz@gnu.org> wrote:

> This should mention the bug number.

Thanks, done

>> +@defun tabulated-list-delete-entry
>> +This function deletes the entry at point.
>> +
>> +It returns a list @code{(id cols)} where @var{id} is the ID of the
>                                      ^
> A comma is missing there.

Thanks, added.

>> +delete entry and @var{cols} is a vector of its column descriptors.
>                ^
> And here.

I don't think a comma is needed here. It's a list of two entries, not
three, so no comma, right?

> Also, the "id" and "cols" inside the list should also have the @var
> markup.

Thanks, added like @code{(@var{id} @var{cols})}

>> +It moves point to the beginning of the deleted entry.
>
> The last sentence is confusing: if the entry is deleted, how can we
> move to its beginning?

Changed to "It moves point to the beginning of the current line."

>> +@defun tabulated-list-header-overlay-p &optional POS
>> +This @code{defsubst} returns non-nil if there is a fake header at
>> +@var{pos}.
>
> We should explain, in a single sentence if possible, what is a "fake
> header".  It is never explained in this section.

Added as "A fake header is used if @code{tabulated-list-use-header-line} is @code{nil} to put the column names at the beginning of the buffer."

>> +@defun tabulated-list-put-tag tag &optional advance
>> +This function puts @var{tag} in the padding area of the current line.
>
> And this should explain what is the padding area, for the same reason.

Added as "The padding area can be empty space at the beginning of the line, the width of which is governed by @code{tabulated-list-padding}."

>> +@var{tag} should be a string, with a length less than or equal to
>> +@code{tabulated-list-padding}.
>
> Every variable mentioned in the manual should be indexed.  So please
> add
>
>  @vindex tabulated-list-padding
>
> before the @defun.

Done (also for tabulated-list-use-header-line)

>> +If @var{change-entry-data} is non-nil, this function modifies the
>> +underlying entry data by setting the appropriate slot of the vector
>> +originally used to print this entry.  If @code{tabulated-list-entries}
>> +has a list value, this is the vector stored within it.
>
> This paragraph is confusing, I cannot understand what that argument
> does just by reading the above text.  (The doc string says the same,
> so it's of no help.)  The confusing parts are "appropriate slot" and
> "originally used to print".  The code simply modifies a component of
> the vector returned by tabulated-list-get-entry, so I wonder why the
> description needs to be that complicated.

Changed to this, which is hopefully clearer:

If @var{change-entry-data} is non-nil, this function modifies the
underlying data (usually the column descriptor in the list
@code{tabulated-list-entries}) by setting the column descriptor of the
vector to @code{desc}.

Thanks,
Alex


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Add-documentation-for-tabulated-list-functions-in-th.patch --]
[-- Type: text/x-patch, Size: 3581 bytes --]

From 5d0a50705a19ad464d141ab3b4880dddf5cf37ea Mon Sep 17 00:00:00 2001
From: Alex Branham <alex.branham@gmail.com>
Date: Sat, 2 Feb 2019 09:59:21 -0600
Subject: [PATCH] Add documentation for tabulated-list functions in the elisp
 manual

* doc/lispref/modes.texi: Add documentation for
  'tabulated-list-delete-entry', 'tabulated-list-get-id',
  'tabulated-list-get-entry', 'tabulated-list-header-overlay-p',
  'tabulated-list-put-tag', and 'tabulated-list-set-col'.

Bug#21074
---
 doc/lispref/modes.texi | 59 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)

diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 143cc7c582..aeac421495 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -1121,6 +1121,65 @@ that tags placed via @code{tabulated-list-put-tag} will not be removed
 from entries that haven't changed (normally all tags are removed).
 @end defun
 
+@defun tabulated-list-delete-entry
+This function deletes the entry at point.
+
+It returns a list @code{(@var{id} @var{cols})}, where @var{id} is the
+ID of the delete entry and @var{cols} is a vector of its column
+descriptors.  It moves point to the beginning of the current line.
+It returns @code{nil} if there is no entry at point.
+
+Note that this function only changes the buffer contents; it does not
+alter @code{tabulated-list-entries}.
+@end defun
+
+@defun tabulated-list-get-id &optional pos
+This @code{defsubst} returns the ID object from
+@code{tabulated-list-entries} (if that is a list) or from the list
+returned by @code{tabulated-list-entries} (if it is a function).  If
+omitted or @code{nil}, @var{pos} defaults to point.
+@end defun
+
+@defun tabulated-list-get-entry &optional pos
+This @code{defsubst} returns the entry object from
+@code{tabulated-list-entries} (if that is a list) or from the list
+returned by @code{tabulated-list-entries} (if it is a function).  This
+will be a vector for the ID at @var{pos}.  If there is no entry at
+@var{pos}, then the function returns @code{nil}.
+@end defun
+
+@vindex tabulated-list-use-header-line
+@defun tabulated-list-header-overlay-p &optional POS
+This @code{defsubst} returns non-nil if there is a fake header at
+@var{pos}.  A fake header is used if
+@code{tabulated-list-use-header-line} is @code{nil} to put the column
+names at the beginning of the buffer.  If omitted or @code{nil},
+@var{pos} defaults to @code{point-min}.
+@end defun
+
+@vindex tabulated-list-padding
+@defun tabulated-list-put-tag tag &optional advance
+This function puts @var{tag} in the padding area of the current line.
+The padding area can be empty space at the beginning of the line, the
+width of which is governed by @code{tabulated-list-padding}.
+@var{tag} should be a string, with a length less than or equal to
+@code{tabulated-list-padding}.  If @var{advance} is non-nil, this
+function advances point by one line.
+@end defun
+
+@defun tabulated-list-set-col col desc &optional change-entry-data
+This function changes the tabulated list entry at point, setting
+@var{col} to @var{desc}.  @var{col} is the column number to change, or
+the name of the column to change.  @var{desc} is the new column
+descriptor, which is inserted via @code{tabulated-list-print-col}.
+
+If @var{change-entry-data} is non-nil, this function modifies the
+underlying data (usually the column descriptor in the list
+@code{tabulated-list-entries}) by setting the column descriptor of the
+vector to @code{desc}.
+@end defun
+
+
 @node Generic Modes
 @subsection Generic Modes
 @cindex generic mode
-- 
2.19.2