[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#37538: [PATCH] Add docstring for `tags-complete-tags-table-file'.
From: |
Eli Zaretskii |
Subject: |
bug#37538: [PATCH] Add docstring for `tags-complete-tags-table-file'. |
Date: |
Thu, 10 Oct 2019 10:49:55 +0300 |
> 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.
- bug#37538: [PATCH] Add docstring for `tags-complete-tags-table-file'., Lars Ingebrigtsen, 2019/10/07
- bug#37538: [PATCH] Add docstring for `tags-complete-tags-table-file'., Eli Zaretskii, 2019/10/07
- bug#37538: [PATCH] Add docstring for `tags-complete-tags-table-file'., Hong Xu, 2019/10/07
- bug#37538: [PATCH] Add docstring for `tags-complete-tags-table-file'., Lars Ingebrigtsen, 2019/10/08
- bug#37538: [PATCH] Add docstring for `tags-complete-tags-table-file'., Hong Xu, 2019/10/09
- bug#37538: [PATCH] Add docstring for `tags-complete-tags-table-file'., Eli Zaretskii, 2019/10/09
- bug#37538: [PATCH] Add docstring for `tags-complete-tags-table-file'., Hong Xu, 2019/10/09
- bug#37538: [PATCH] Add docstring for `tags-complete-tags-table-file'.,
Eli Zaretskii <=
- bug#37538: [PATCH] Add docstring for `tags-complete-tags-table-file'., Hong Xu, 2019/10/11
- bug#37538: [PATCH] Add docstring for `tags-complete-tags-table-file'., Eli Zaretskii, 2019/10/12
- bug#37538: [PATCH] Add docstring for `tags-complete-tags-table-file'., Hong Xu, 2019/10/12
- bug#37538: [PATCH] Add docstring for `tags-complete-tags-table-file'., Eli Zaretskii, 2019/10/12