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

[Eli Zaretskii <eliz@gnu.org>]

> Cc: larsi@gnus.org, 37538@debbugs.gnu.org
> From: Hong Xu <hong@topbug.net>
> 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.