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

From: Alex Branham <[email-masked]>
Date: Mon, 21 Jan 2019 10:12:22 -0600

On Sat 19 Jan 2019 at 02:25, Eli Zaretskii <[email-masked]> wrote:

> Ah, I wasn't aware there was a previous context for this bug.  (Please
> in the future say something to put things in their context, otherwise
> one needs to deduce from the bug number that it might have been
> discussed previously, and go look up that discussion.  I usually just
> ignore the bug number.)

Will do, sorry. I'm still trying to find a good way to interact with the
bugtracker.

> After looking into this for some time, I think we should document
> functions of tabulated-mode that are frequently used by its clients,
> of which there are some in the Emacs tree.  The above 2 functions
> aren't the only ones undocumented in the manual.  So either we
> document them all, or we'd need more serious rationale for documenting
> just those 2.  Would you like to see what other tabulated-mode
> functions are candidates for addition to the manual?

I'm not sure there's a great way to decide what needs documentation and
what doesn't. Glancing through the code in the Emacs tree, these are the
functions that seem to get used fairly often by modes that derive from
tabulated-list-mode:

- tabulated-list-delete-entry
- tabulated-list-get-entry
- tabulated-list-get-id
- tabulated-list-header-overlay-p
- tabulated-list-put-tag
- tabulated-list-set-col

So perhaps start with those?

I got the rest of your comments (thanks!) and will incorporate them into
a follow-up patch once we decide what exactly needs to get documented.

Alex