RE: Opaque objects and Emacs documentation

[Drew Adams]

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

And there is `finder-commentary'.  It could
be bound to a help key (`C-h <something>').

The version of `finder-commentary' I have in
`finder+.el' names the buffer `*Commentary, <file>*'
where <file> is the file the Commentary is from,
not just `*Finder-package*'.  That labels it well,
and lets you easily have more than one such help
buffer.

https://www.emacswiki.org/emacs/download/finder%2b.el

https://www.emacswiki.org/emacs/FinderMode

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

I agree with that.  (But I also think that a helpful
Commentary is a good thing, and I miss the Commentary
sections of yesteryear.)