From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Hong Xu Newsgroups: gmane.emacs.bugs Subject: bug#37538: [PATCH] Add docstring for `tags-complete-tags-table-file'. Date: Wed, 9 Oct 2019 15:58:46 -0700 Message-ID: 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> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 7bit Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="144130"; mail-complaints-to="usenet@blaine.gmane.org" User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Thunderbird/60.9.0 Cc: larsi@gnus.org, 37538@debbugs.gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Thu Oct 10 00:59: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 1iIKvH-000bKq-25 for geb-bug-gnu-emacs@m.gmane.org; Thu, 10 Oct 2019 00:59:11 +0200 Original-Received: from localhost ([::1]:60730 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iIKvF-0004te-7T for geb-bug-gnu-emacs@m.gmane.org; Wed, 09 Oct 2019 18:59:09 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:60967) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iIKv8-0004tS-R6 for bug-gnu-emacs@gnu.org; Wed, 09 Oct 2019 18:59:03 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1iIKv7-0000Mo-OX for bug-gnu-emacs@gnu.org; Wed, 09 Oct 2019 18:59:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:45600) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1iIKv7-0000Mh-Ll for bug-gnu-emacs@gnu.org; Wed, 09 Oct 2019 18:59:01 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1iIKv7-0000nr-Jr for bug-gnu-emacs@gnu.org; Wed, 09 Oct 2019 18:59:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Hong Xu Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 09 Oct 2019 22:59: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.15706619393079 (code B ref 37538); Wed, 09 Oct 2019 22:59:01 +0000 Original-Received: (at 37538) by debbugs.gnu.org; 9 Oct 2019 22:58:59 +0000 Original-Received: from localhost ([127.0.0.1]:54421 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iIKv4-0000na-Pb for submit@debbugs.gnu.org; Wed, 09 Oct 2019 18:58:59 -0400 Original-Received: from sender4-of-o54.zoho.com ([136.143.188.54]:21423) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iIKv2-0000nS-UJ for 37538@debbugs.gnu.org; Wed, 09 Oct 2019 18:58:57 -0400 ARC-Seal: i=1; a=rsa-sha256; t=1570661927; cv=none; d=zoho.com; s=zohoarc; b=O03EVXeK/mDLq/1kEYpctasFWb0KkAafFL8XzpGVECfznJAy8n46XnCjl6T5aK3uBRBjQ93dNcbG9k9Mm49o3h6MTBiGsyS97V3/WC6YSsntYMsPjB9sGJ9DkKzYx+ddPpy8DMrVhoviFxw09DPJ/2PhgX8qke2xiC3hFmN6JOI= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zoho.com; s=zohoarc; t=1570661927; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:MIME-Version:Message-ID:References:Subject:To; bh=p53PHZJbNpqC80EwMKeU5qANAUG097sLaH63nuHo6aI=; b=TVDxcr4UJzQhr57mxxpxD4yAjmn5yWG3IRJgNVlnIKZSx8rx9f2ZZ0aFOt2DL9E44j6Ay1mN7qEQljPVhX/0Sv+5UKsb9uQdgYL3I6iRtwzo2lJZEI8UZEGXVNlzpCN7b5idzB3TydW2V4hxIsh/0fPmhxRlHsz0VwF5nFb6jnY= ARC-Authentication-Results: i=1; mx.zoho.com; dkim=pass header.i=topbug.net; spf=pass smtp.mailfrom=hong@topbug.net; dmarc=pass header.from= header.from= DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; t=1570661927; s=zoho; d=topbug.net; i=hong@topbug.net; h=Subject:To:Cc:References:From:Message-ID:Date:MIME-Version:In-Reply-To:Content-Type:Content-Transfer-Encoding; l=1575; bh=p53PHZJbNpqC80EwMKeU5qANAUG097sLaH63nuHo6aI=; b=VrnmMZNjNYTM48qMXrGUK/6IFtgoDReBk2w5PkuDJx39XPNeC6TaZqZrQ5ug1MEv ZRl/IgRrXde1NKJqpmuZm8Hdyj8bOG+qG+L5KGSgeOLs00eiFVH2ysUObB5VDzYCvHn hlWBE0j6FxBkY/s1IPC8X5+XtXX8ASEqDYJRxlJ8= Original-Received: from [192.168.88.88] (69-215-149-151.lightspeed.sntcca.sbcglobal.net [69.215.149.151]) by mx.zohomail.com with SMTPS id 157066192718637.824944478373936; Wed, 9 Oct 2019 15:58:47 -0700 (PDT) Openpgp: preference=signencrypt In-Reply-To: <83a7aawdar.fsf@gnu.org> Content-Language: en-US X-ZohoMailClient: External 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:168819 Archived-At: On 10/9/19 1:09 AM, Eli Zaretskii wrote: >> Cc: Eli Zaretskii , 37538@debbugs.gnu.org >> From: Hong Xu >> Date: Tue, 8 Oct 2019 23:39:08 -0700 >> >> On 10/8/19 9:21 AM, Lars Ingebrigtsen wrote: >>> >>> The problem is that `(elisp) Programmed Completion' (at least in Emacs >>> 27) doesn't mention a WHAT parameter at all, so it's unclear what this >>> refers to. >> >> How about the following change? > > I don't see how it solves the problem, sorry. It attempts to assign > some significance to the ordinal number of the argument WHAT, in the > hope that the reader will be able to connect the dots. But a good > documentation should not leave the dots unconnected, it should spell > them out, ideally in one place. > > 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. 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.