bug#38996: 26.3; Missing documentation for `list-at-point' function in elisp manual.

bug#38996: 26.3; Missing documentation for `list-at-point' function in elisp manual.

[Mark Harig via Bug reports for GNU Emacs, the Swiss army knife of text editors]

[-- Attachment #1: Type: text/plain, Size: 888 bytes --]

Emacs Maintainers,
Several searches at debbugs.gnu.org did not turn up any reports for this minor documentation omission.
The NEWS file for Emacs 26.2/.3 documents changes to `thing-at-point', including mention of the function `list-at-point'.  C-h f (describe-function) provides documentation of `list-at-point', but C-h S (info-lookup-symbol) for `list-at-point' responds with "Not documented as a symbol: list-at-point'.  A check of the node in the elisp manual that documents `thing-at-point' does not show any mention of `list-at-point', nor does the previous node ("Near Point").  If `list-at-point' is documented elsewhere in the elisp manual, then an index manual entry is needed for this function.  Without this documentation, it is still possible to use `list-at-point', but when it is not documented in the manual, users might not know that it exists.
(End of report.)

[-- Attachment #2: Type: text/html, Size: 1270 bytes --]

bug#38996: 26.3; Missing documentation for `list-at-point' function in elisp manual.

[Eli Zaretskii]

> Date: Mon, 6 Jan 2020 20:33:15 +0000 (UTC)
> From: Mark Harig via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
> 
> The NEWS file for Emacs 26.2/.3 documents changes to `thing-at-point', including mention of the function
> `list-at-point'.  C-h f (describe-function) provides documentation of `list-at-point', but C-h S
> (info-lookup-symbol) for `list-at-point' responds with "Not documented as a symbol: list-at-point'.  A check of
> the node in the elisp manual that documents `thing-at-point' does not show any mention of `list-at-point', nor
> does the previous node ("Near Point").  If `list-at-point' is documented elsewhere in the elisp manual, then an
> index manual entry is needed for this function.  Without this documentation, it is still possible to use
> `list-at-point', but when it is not documented in the manual, users might not know that it exists.

Thank you for your report.

We don't document every function in the manual: that would make the
manual too large (it already prints as 2 very thick volumes).  This
function is new, and has no callers inside Emacs, so whether it is
important enough to warrant a place in the manual remains to be seen.

For discoverability, we rely on built-in Help features such as
'apropos', and yes, on people reading NEWS when they start using a new
version, because reading that will tell them about changes in a much
more efficient way than the same information buried among many
hundreds of pages of the manual.

So I think we should wait and see if this function needs to be added
to the manual.

bug#38996: 26.3; Missing documentation for `list-at-point' function in elisp manual.

[Stefan Kangas]

tags 38996 + notabug wontfix
close 38996
thanks

Eli Zaretskii <eliz@gnu.org>:

> So I think we should wait and see if this function needs to be added
> to the manual.

I agree, and I'm therefore closing this bug report.

Best regards,
Stefan Kangas

bug#38996: 26.3; Missing documentation for `list-at-point' function in elisp manual.

[Mark Harig via Bug reports for GNU Emacs, the Swiss army knife of text editors]

[-- Attachment #1: Type: text/plain, Size: 1075 bytes --]

> We don't document every function in the manual: that would make the> manual too large (it already prints as 2 very thick volumes).  This> function is new, and has no callers inside Emacs, so whether it is> important enough to warrant a place in the manual remains to be seen.> > For discoverability, we rely on built-in Help features such as> 'apropos', and yes, on people reading NEWS when they start using a new> version, because reading that will tell them about changes in a much> more efficient way than the same information buried among many> hundreds of pages of the manual.
OK. Going forward, how are end users to know which functions have notbeen documented on purpose and which have not been documented due tooversight?  It might be worth considering adding to future NEWS, whena new function or variable is added, a some brief note saying that"this function/variable will not (yet) be documented in one of themanuals."  Without that, it is impossible for a user to know whetherthe lack of documentation is intentional or an error to be reported here.
---

[-- Attachment #2: Type: text/html, Size: 2350 bytes --]

bug#38996: 26.3; Missing documentation for `list-at-point' function in elisp manual.

[Eli Zaretskii]

> Date: Wed, 8 Jan 2020 17:50:16 +0000 (UTC)
> From: Mark Harig via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
> 
> OK. Going forward, how are end users to know which functions have not
> been documented on purpose and which have not been documented due to
> oversight?

I don't think there should be a way.  If you think something should be
there, and you have a good reason, feel free to report it as a bug.
At worst, you will hear an explanation why it's not an omission; no
harm done.