GNU bug report logs - #44858
[PATCH] Make byte-compiler warn about wide docstrings

Previous Next

Full log

View this message in rfc822 format

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 44858 <at> debbugs.gnu.org
Subject: bug#44858: [PATCH] Make byte-compiler warn about wide docstrings
Date: Thu, 31 Dec 2020 05:42:16 +0100

Stefan Kangas <stefan <at> 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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.