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

[Eli Zaretskii]

> 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.