Re: Opaque objects and Emacs documentation

[Dmitry Gutov]

On 24.07.2020 08:45, Eli Zaretskii wrote:
> > From: Dmitry Gutov <dgutov@yandex.ru>
> > Date: Fri, 24 Jul 2020 03:43:41 +0300
> >
> > Doesn't the Commentary cover most (all?) of the above?
>
> Documenting stuff in the commentary is better than nothing, but it is
> sub-optimal: our Help commands don't scan comments, so the information
> that is only in comments is less discoverable, certainly by users.

We do have 'M-x describe-package', though (C-h P).

> Therefore, I think any information important to users should be in doc
> strings and the manual, not just in comments.

I agree, but it's not like we can describe what the "current project" is 
in concrete terms in a user-facing command.

As for the manual, we already talked about this. Hopefully when you 
start on the alternative project backend, it can persuade you to include 
more higher level language in the descriptions.