bug#37538: [PATCH] Add docstring for `tags-complete-tags-table-file'.

[Hong Xu <hong@topbug.net>]

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.