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

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

[Xu Chunyang]

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*

#+BEGIN_EXAMPLE
Instance Allocated Slots:

	Name	Type	Default	Doc
	————	————	———————	———
	name	t	nil	  The name of the source.
  A string which is also the heading which appears
  above the list of matches from the source. Must be unique.
	header-name	t	nil	  A function returning the display string of the header.
  Its argument is the name of the source. This attribute is useful to
  add an additional information with the source name.
  It doesn't modify the name of the source.
	init	t	nil	  Function called with no parameters when helm is started.
  It is useful for collecting current state information which can be
  used to create the list of candidates later.
  Initialization of `candidates-in-buffer' is done here
  with `helm-init-candidates-in-buffer'.
#+END_EXAMPLE

It seems Emacs is trying to show everything within a table without
considering :documentation can be long.

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

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

[Lars Ingebrigtsen]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> 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?

I've now done this in Emacs 28.

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