|
From: | Hong Xu |
Subject: | bug#37538: [PATCH] Add docstring for `tags-complete-tags-table-file'. |
Date: | Wed, 9 Oct 2019 15:58:46 -0700 |
User-agent: | Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Thunderbird/60.9.0 |
On 10/9/19 1:09 AM, Eli Zaretskii wrote:
Cc: Eli Zaretskii <eliz@gnu.org>, 37538@debbugs.gnu.org From: Hong Xu <hong@topbug.net> 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.
[Prev in Thread] | Current Thread | [Next in Thread] |