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

[Eli Zaretskii <eliz@gnu.org>]

> 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}.
> >
> > 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.