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

Previous Next

Full log

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Alex Branham <alex.branham <at> gmail.com>
Cc: 21074 <at> debbugs.gnu.org, mbork <at> mbork.pl
Subject: Re: bug#21074: [PATCH] Add docs for two tabulated-list functions
Date: Fri, 01 Feb 2019 11:28:17 +0200

> From: Alex Branham <alex.branham <at> gmail.com>
> Cc: Marcin Borkowski <mbork <at> mbork.pl>, 21074 <at> 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}.
> >
> > 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.

  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.

Previous Next

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