bug#30998: 27.0.50; The Help for defclass with multiline documentation is very hard to read

[Lars Ingebrigtsen]

Xu Chunyang <mail@xuchunyang.me> writes:

> I don't know if defclass requires that :documentation must occupies just
> a single line. Helm uses many multiple lines string for that slot, please see
>
> https://github.com/emacs-helm/helm/blob/6a34d57f416e4194e6d3207b558d3a00cdf2b955/helm-source.el#L54
>
> 'C-h f helm-source' is very hard to read, the following is a part of *Help*

For a build-in example, see `C-h f registry-db' (included below).

So the problem here is with the :documentation strings for the slots:
They can be multi-line, and `C-h f' should format that situation
different.

But even with single-line descriptions, it's unreadable, really, unless
you have an Emacs window that's 150 characters wide.

Perhaps this should be reformatted completely, with the :documentation
string on a separate line?

----
Class description:
registry-db is a type (of kind ‘eieio--class’) in ‘registry.el’.
 Inherits from ‘eieio-persistent’.
Instance Allocated Slots:

        Name    Type    Default Doc
        ————    ————    ——————— ———
        file    string  unbound The save file for this persistent object.
This must be a string, and must be specified when the new object is
instantiated.
        version (or null float) nil     The registry version.
        max-size        integer (symbol-value 'most-positive-fixnum)    The 
maximum number of registry entries.
        prune-factor    float   0.1     Prune to (:max-size * :prune-factor) 
less
    than the :max-size limit.  Should be a float between 0 and 1.
        tracked t       nil     The tracked (indexed) fields, a list of symbols.
        precious        t       nil     The precious fields, a list of symbols.
        tracker hash-table      unbound The field tracking hash table.
        data    hash-table      unbound The data hash table.
----


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