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

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

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


Thanks Eli, I'm going through this now and just have a couple quick
questions about your comments:

On Sat 19 Jan 2019 at 02:25, Eli Zaretskii <eliz@gnu.org> wrote:

> In any case, a few minor comments for the patch:
>
>> +@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...

?

>> +                                             This will be an ID object
>> +from @var{tabulated-list-entries}.
>
> An element of tabulated-list-entries could be a function, and what
> does this return in that case?  This should be spelled out in the
> manual, otherwise the reader will be left out wondering.

That's not my understanding. I think tabulated-list-entries can either
be a list with elements that look like (id col), or be a function that
returns that list. As I understand, elements of the list can't be
functions. If that's correct, I think it's clear enough that the ID of
the entry at point is determined by the function
'tabulated-list-entries' and we don't need to mention it (the wording
gets complicated). If you still want to add it, perhaps something like:

This will be an ID object from @var{tabulated-list-entries} or
calculated from that function if @var{tabulated-list-entries} is a
function.

What do you think?

Thanks,
Alex

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 487 bytes --]