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

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

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


On Fri 01 Feb 2019 at 03:28, Eli Zaretskii <eliz@gnu.org> wrote:

>> From: Alex Branham <alex.branham@gmail.com>
>> Cc: Marcin Borkowski <mbork@mbork.pl>, 21074@debbugs.gnu.org
>> Date: Tue, 22 Jan 2019 15:03:41 -0600
>>
>> >> +@defun tabulated-list-get-id &optional pos
>> >
>> > In the code, this is a defsubst, not a defun.
>>
>> How do we document these in the elisp manual? I'm struggling to find an
>> example. Is it just:
>>
>> @findex{tabulated-list-get-id}
>> tabulated-list-get-id &optional pod
>>
>> This function returns...
>>
>> ?
>
> I think just say in the description something like "This
> @code{defsubst} returns...".

>> This will be an ID object from @var{tabulated-list-entries} or
>> calculated from that function if @var{tabulated-list-entries} is a
>> function.
>
>   This is 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).
>
> Note: @code, not @var, because tabulated-list-entries is a literal
> symbol, not an argument of a function.

Thanks. I think the attached patch incorporates all your comments, let
me know if I missed something.

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: 3258 bytes --]

From dcec7e84ccf9a612cfed6a9f607dc021eb964e1a 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'.
---
 doc/lispref/modes.texi | 53 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)

diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 143cc7c582..4635a5c6e4 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -1121,6 +1121,59 @@ 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{(id 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 deleted entry.  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
+
+@defun tabulated-list-header-overlay-p &optional POS
+This @code{defsubst} returns non-nil if there is a fake header at
+@var{pos}.  If omitted or @code{nil}, @var{pos} defaults to
+@code{point-min}.
+@end defun
+
+@defun tabulated-list-put-tag tag &optional advance
+This function puts @var{tag} in the padding area of the current line.
+@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 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.
+@end defun
+
+
 @node Generic Modes
 @subsection Generic Modes
 @cindex generic mode
-- 
2.19.2