GNU bug report logs - #21074
25.0.50; Incomplete docs for tabulated-list-mode

Previous Next

Full log

Message #26 received at 21074 <at> debbugs.gnu.org (full text, mbox):

From: Alex Branham <alex.branham <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 21074 <at> debbugs.gnu.org, Marcin Borkowski <mbork <at> mbork.pl>
Subject: Re: bug#21074: [PATCH] Add docs for two tabulated-list functions
Date: Tue, 22 Jan 2019 15:03:41 -0600

[Message part 1 (text/plain, inline)]

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 <at> 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

[signature.asc (application/pgp-signature, inline)]

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.