bug#50146: 26.3; Doc of `MODE-' things created by `define-globalized-minor-mode'

bug#50146: 26.3; Doc of `MODE-' things created by `define-globalized-minor-mode'

[Drew Adams]

A user can be puzzled by `C-h v' and `C-h f' completion showing the
names of variables and functions that get created by macro
`define-globalized-minor-mode'.  `C-h v' and `C-h f' are primary means
of discovery.

If a user chooses such a name from completion she's not helped, but
further pushed into puzzlement.  She'll see something like this:

  foo-mode-set-explicitly is a Lisp function in 'foobar.el'.

  (foo-mode-set-explicitly)

And clicking that file-name link won't help at all, but will add to the
confusion.

Can we not fix this somehow?

If nothing really reasonable can be found to fix this, maybe a kludge
improvement would be to at least add a doc string to such a created
thing, which says that the thing was created by
`define-globalized-minor-mode' and perhaps points to that macro.  And
perhaps that doc string could point to the corresponding mode command,
so users can consult its doc (which won't mention the thing created, but
at least might get users closer to what's going on).

In GNU Emacs 26.3 (build 1, x86_64-w64-mingw32)
 of 2019-08-29
Repository revision: 96dd0196c28bc36779584e47fffcca433c9309cd
Windowing system distributor `Microsoft Corp.', version 10.0.19042
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

bug#50146: 26.3; Doc of `MODE-' things created by `define-globalized-minor-mode'

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> Date: Sat, 21 Aug 2021 15:46:38 +0000
> 
> A user can be puzzled by `C-h v' and `C-h f' completion showing the
> names of variables and functions that get created by macro
> `define-globalized-minor-mode'.  `C-h v' and `C-h f' are primary means
> of discovery.
> 
> If a user chooses such a name from completion she's not helped, but
> further pushed into puzzlement.  She'll see something like this:
> 
>   foo-mode-set-explicitly is a Lisp function in 'foobar.el'.
> 
>   (foo-mode-set-explicitly)
> 
> And clicking that file-name link won't help at all, but will add to the
> confusion.
> 
> Can we not fix this somehow?

Please provide a specific example or two.  I tried looking at
global-visual-line-mode, and didn't see anything like what you
describe.

bug#50146: [External] : Re: bug#50146: 26.3; Doc of `MODE-' things created by `define-globalized-minor-mode'

[Drew Adams]

> Please provide a specific example or two.  I tried looking at
> global-visual-line-mode, and didn't see anything like what you
> describe.

emacs -Q

(define-minor-mode foo-mode "..."
  :init-value nil :global t :group 'convenience)

(defun turn-on-foo-mode () "..." (foo-mode 1))

(define-globalized-minor-mode foo-global-mode
  foo-mode turn-on-foo-mode :group 'convenience)

C-h f foo TAB
___

You see this in *Completions*:

Click on a completion to select it.
In this buffer, type RET to select the completion near point.

Possible completions are:
foo-global-mode 	foo-global-mode-check-buffers
foo-global-mode-cmhh 	foo-global-mode-enable-in-buffers
foo-mode 	foo-mode-set-explicitly
footnote-mode
___

`foo-mode-set-explicitly' is created by the macro.
If you click that name in *Completions* you see this:
___

foo-mode-set-explicitly is a Lisp function.

(foo-mode-set-explicitly)

Not documented.
___

Same thing, if you use `C-h v foo TAB' and choose
`foo-mode-set-explicitly': the help for the var is
just as vacuous.

These automatically created things seems like noise,
for users.  If they're intended to be under the covers
then maybe they should be more under the covers.

If they're intended to be usable by, or understandable
to, users, then maybe they should have some doc that at
least tries to dispel some of the possible confusion.

bug#50146: [External] : Re: bug#50146: 26.3; Doc of `MODE-' things created by `define-globalized-minor-mode'

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> CC: "50146@debbugs.gnu.org" <50146@debbugs.gnu.org>
> Date: Sat, 21 Aug 2021 16:25:59 +0000
> 
> C-h f foo TAB
> ___
> 
> You see this in *Completions*:
> 
> Click on a completion to select it.
> In this buffer, type RET to select the completion near point.
> 
> Possible completions are:
> foo-global-mode 	foo-global-mode-check-buffers
> foo-global-mode-cmhh 	foo-global-mode-enable-in-buffers
> foo-mode 	foo-mode-set-explicitly
> footnote-mode
> ___
> 
> `foo-mode-set-explicitly' is created by the macro.
> If you click that name in *Completions* you see this:
> ___
> 
> foo-mode-set-explicitly is a Lisp function.
> 
> (foo-mode-set-explicitly)
> 
> Not documented.
> ___

When I see something that is "not documented", I conclude that it's an
internal function without a need for documentation.  YMMV.

bug#50146: 26.3; Doc of `MODE-' things created by `define-globalized-minor-mode'

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> When I see something that is "not documented", I conclude that it's an
> internal function without a need for documentation.  YMMV.

Yup -- it's an internal function used by the easy-mmode machinery, and
as such shouldn't be documented.  So I'm closing this bug report.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no