bug#44858: [PATCH] Make byte-compiler warn about wide docstrings

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

> But this line has to be like this if `C-h f' is to show anything but
> (&rest spec) for the function parameters.  So should we just add some
> special case where we ignore the last line if it matches "^([^)])$"?

Sounds reasonable.

>
> 2. cl-defstruct
>
> In epg-context--make:
> epg.el:197:30: Warning: docstring wider than 80 characters
>
> Here I can't figure out why the docstring is too long.  Using
> `macrostep-expand' doesn't reveal why.  Does anyone have any ideas?

Hm.  The doc string (as displayed by the help functions) is:

epg-context--make is a compiled Lisp function in ‘epg.el’.

(epg-context--make PROTOCOL &optional ARMOR TEXTMODE INCLUDE-CERTS
CIPHER-ALGORITHM DIGEST-ALGORITHM COMPRESS-ALGORITHM)

  This function does not change global state, including the match data.

Constructor for objects of type ‘epg-context’.

Has that been folded at some point after your function has looked at it?

> 3. defclass
>
> These are autogenerated docstrings that I don't trivially see how we can
> just wrap as it's the first line that is too long:
>
> In jsonrpc-request:
> jsonrpc.el:349:15: Warning: docstring wider than 80 characters
>
> In toplevel form:
> cedet/ede/proj-comp.el:71:26: Warning: docstring wider than 80 characters
>
> I suppose we need to rethink these, somehow.

These bits can be filled:

Specialized Methods:

‘jsonrpc--next-request-id’ ((this jsonrpc-connection))
Retrieve the slot ‘-next-request-id’ from an object of class 
‘jsonrpc-connection’.

These bits:

Instance Allocated Slots:

        Name    Type    Default Doc
        ————    ————    ——————— ———
        name    t       unbound A name for the connection
        -request-dispatcher     t       #'ignore        Dispatcher for remotely 
invoked requests.
        -notification-dispatcher        t       #'ignore        Dispatc


Have to be reformatted -- just moving the Doc to the next line should be
sufficient for most things.

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