From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#21074: [PATCH] Add docs for two tabulated-list functions Date: Sat, 02 Feb 2019 18:33:01 +0200 Message-ID: <83h8dmw3pe.fsf@gnu.org> References: <87a8uwmq0d.fsf@mbork.pl> <871s5diy1q.fsf@gmail.com> <83won5d9ll.fsf@gnu.org> <87zhs1hfo7.fsf@gmail.com> <83k1j1awba.fsf@gnu.org> <87k1iwl80i.fsf@gmail.com> <83zhrfyi1a.fsf@gnu.org> <87y36y9nzg.fsf@gmail.com> Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="30439"; mail-complaints-to="usenet@blaine.gmane.org" Cc: 21074@debbugs.gnu.org, mbork@mbork.pl To: Alex Branham Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sat Feb 02 17:34:11 2019 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1gpyF8-0007oE-WC for geb-bug-gnu-emacs@m.gmane.org; Sat, 02 Feb 2019 17:34:11 +0100 Original-Received: from localhost ([127.0.0.1]:44072 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gpyF7-0000oW-RS for geb-bug-gnu-emacs@m.gmane.org; Sat, 02 Feb 2019 11:34:09 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:35960) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gpyF1-0000o7-Ib for bug-gnu-emacs@gnu.org; Sat, 02 Feb 2019 11:34:04 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gpyF0-0004ZO-L2 for bug-gnu-emacs@gnu.org; Sat, 02 Feb 2019 11:34:03 -0500 Original-Received: from debbugs.gnu.org ([209.51.188.43]:57262) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1gpyF0-0004ZD-Fu for bug-gnu-emacs@gnu.org; Sat, 02 Feb 2019 11:34:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1gpyF0-0007LM-BZ for bug-gnu-emacs@gnu.org; Sat, 02 Feb 2019 11:34:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 02 Feb 2019 16:34:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 21074 X-GNU-PR-Package: emacs Original-Received: via spool by 21074-submit@debbugs.gnu.org id=B21074.154912523528215 (code B ref 21074); Sat, 02 Feb 2019 16:34:02 +0000 Original-Received: (at 21074) by debbugs.gnu.org; 2 Feb 2019 16:33:55 +0000 Original-Received: from localhost ([127.0.0.1]:56543 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1gpyEt-0007L1-73 for submit@debbugs.gnu.org; Sat, 02 Feb 2019 11:33:55 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:49685) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1gpyEr-0007Ko-4i for 21074@debbugs.gnu.org; Sat, 02 Feb 2019 11:33:53 -0500 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:41396) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gpyEb-0004Cc-Tg; Sat, 02 Feb 2019 11:33:41 -0500 Original-Received: from [176.228.60.248] (port=3289 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1gpyEU-0005t4-IO; Sat, 02 Feb 2019 11:33:36 -0500 In-reply-to: <87y36y9nzg.fsf@gmail.com> (message from Alex Branham on Sat, 02 Feb 2019 10:03:31 -0600) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.51.188.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:155025 Archived-At: > From: Alex Branham > Cc: mbork@mbork.pl, 21074@debbugs.gnu.org > Date: Sat, 02 Feb 2019 10:03:31 -0600 > > Thanks. I think the attached patch incorporates all your comments, let > me know if I missed something. Looks good. A couple of minor gotchas, though. > * doc/lispref/modes.texi: Add documentation for > 'tabulated-list-delete-entry', 'tabulated-list-get-id', > 'tabulated-list-get-entry', 'tabulated-list-header-overlay-p', > 'tabulated-list-put-tag', and 'tabulated-list-set-col'. This should mention the bug number. > +@defun tabulated-list-delete-entry > +This function deletes the entry at point. > + > +It returns a list @code{(id cols)} where @var{id} is the ID of the ^ A comma is missing there. > +delete entry and @var{cols} is a vector of its column descriptors. ^ And here. Also, the "id" and "cols" inside the list should also have the @var markup. > +It moves point to the beginning of the deleted entry. The last sentence is confusing: if the entry is deleted, how can we move to its beginning? > +@defun tabulated-list-header-overlay-p &optional POS > +This @code{defsubst} returns non-nil if there is a fake header at > +@var{pos}. We should explain, in a single sentence if possible, what is a "fake header". It is never explained in this section. > +@defun tabulated-list-put-tag tag &optional advance > +This function puts @var{tag} in the padding area of the current line. And this should explain what is the padding area, for the same reason. > +@var{tag} should be a string, with a length less than or equal to > +@code{tabulated-list-padding}. Every variable mentioned in the manual should be indexed. So please add @vindex tabulated-list-padding before the @defun. > +If @var{change-entry-data} is non-nil, this function modifies the > +underlying entry data by setting the appropriate slot of the vector > +originally used to print this entry. If @code{tabulated-list-entries} > +has a list value, this is the vector stored within it. This paragraph is confusing, I cannot understand what that argument does just by reading the above text. (The doc string says the same, so it's of no help.) The confusing parts are "appropriate slot" and "originally used to print". The code simply modifies a component of the vector returned by tabulated-list-get-entry, so I wonder why the description needs to be that complicated. Thanks again for working on this.