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#37538: [PATCH] Add docstring for `tags-complete-tags-table-file'. Date: Thu, 10 Oct 2019 10:49:55 +0300 Message-ID: <831rvlt4yk.fsf@gnu.org> References: <36bef08c-45b5-9cce-5374-d4de4260d39a@topbug.net> <838sq8j0vl.fsf@gnu.org> <7e0290a2-e80b-f566-9c3b-894aaf4e5d9d@topbug.net> <87o8yt9oql.fsf@gnus.org> <83y2xwzfz0.fsf@gnu.org> <860671c8-787c-512c-8df6-ea1d9dfc2f5b@topbug.net> <874l0j1a3j.fsf@gnus.org> <663aaf32-97c4-0723-1a30-a644938bd21f@topbug.net> <83a7aawdar.fsf@gnu.org> Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="175498"; mail-complaints-to="usenet@blaine.gmane.org" Cc: larsi@gnus.org, 37538@debbugs.gnu.org To: Hong Xu Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Thu Oct 10 09:51: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.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1iITE7-000jU4-0z for geb-bug-gnu-emacs@m.gmane.org; Thu, 10 Oct 2019 09:51:11 +0200 Original-Received: from localhost ([::1]:34786 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iITE5-0008GG-It for geb-bug-gnu-emacs@m.gmane.org; Thu, 10 Oct 2019 03:51:09 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:53556) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iITDz-0008Fv-58 for bug-gnu-emacs@gnu.org; Thu, 10 Oct 2019 03:51:04 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1iITDy-0002un-22 for bug-gnu-emacs@gnu.org; Thu, 10 Oct 2019 03:51:03 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:46192) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1iITDx-0002uh-Va for bug-gnu-emacs@gnu.org; Thu, 10 Oct 2019 03:51:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1iITDx-0007SA-Rt for bug-gnu-emacs@gnu.org; Thu, 10 Oct 2019 03:51:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 10 Oct 2019 07:51:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 37538 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: fixed patch Original-Received: via spool by 37538-submit@debbugs.gnu.org id=B37538.157069382028598 (code B ref 37538); Thu, 10 Oct 2019 07:51:01 +0000 Original-Received: (at 37538) by debbugs.gnu.org; 10 Oct 2019 07:50:20 +0000 Original-Received: from localhost ([127.0.0.1]:55013 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iITDH-0007RC-Jj for submit@debbugs.gnu.org; Thu, 10 Oct 2019 03:50:19 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:44433) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iITDF-0007Qw-GJ for 37538@debbugs.gnu.org; Thu, 10 Oct 2019 03:50:17 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:34784) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1iITD9-0002ep-VM; Thu, 10 Oct 2019 03:50:12 -0400 Original-Received: from [176.228.60.248] (port=4984 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1iITD9-0004OI-89; Thu, 10 Oct 2019 03:50:11 -0400 In-reply-to: (message from Hong Xu on Wed, 9 Oct 2019 15:58:46 -0700) 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:168848 Archived-At: > Cc: larsi@gnus.org, 37538@debbugs.gnu.org > From: Hong Xu > Date: Wed, 9 Oct 2019 15:58:46 -0700 > > > I actually don't understand why we would like to send the reader to > > the manual, instead of describing the effects of WHAT in the doc > > string. Can we just say it right there? > > > > The description was quite long and I don't think it is justifiable to copy so much text over here to the docstring, plus there are additional reference in the referred manual section. If you show me what long description you had in mind, I could try saying that more concisely as appropriate for a doc string. > IMO the docstring here really tells the reader that this is a standard completion function -- I doubt anyone would consult this docstring to call `tags-complete-tags-table-file', but most likely want to understand that this is a completion function so that they can better understand the codebase. To read the referred portion of the manual, for the purpose of understanding the codebase, is a somewhat inevitable task by itself. There are different use cases for reading the doc string. you seem to be thinking of only one: the first-time reading by someone who has never used this function or any of the other completion APIs. But there's also another, no less important use case: a reading by someone who already knows most of this stuff, but just doesn't remember which argument is which, and in what order to specify them. For these users, a short description of each argument is all that's needed.