From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Stefan Kangas Newsgroups: gmane.emacs.bugs Subject: bug#44858: [PATCH] Make byte-compiler warn about wide docstrings Date: Wed, 30 Dec 2020 04:07:14 -0800 Message-ID: References: <87zh34wfxo.fsf@gnus.org> <87v9dss2ic.fsf@gnus.org> Mime-Version: 1.0 Content-Type: text/plain; charset="UTF-8" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="37912"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 44858@debbugs.gnu.org To: Lars Ingebrigtsen Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Wed Dec 30 13:08:09 2020 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1kuaGv-0009l4-L9 for geb-bug-gnu-emacs@m.gmane-mx.org; Wed, 30 Dec 2020 13:08:09 +0100 Original-Received: from localhost ([::1]:55206 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kuaGu-0003n6-K8 for geb-bug-gnu-emacs@m.gmane-mx.org; Wed, 30 Dec 2020 07:08:08 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:52508) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kuaGo-0003my-8K for bug-gnu-emacs@gnu.org; Wed, 30 Dec 2020 07:08:02 -0500 Original-Received: from debbugs.gnu.org ([209.51.188.43]:58735) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1kuaGo-0006C8-0M for bug-gnu-emacs@gnu.org; Wed, 30 Dec 2020 07:08:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1kuaGn-0000eJ-Qj for bug-gnu-emacs@gnu.org; Wed, 30 Dec 2020 07:08:01 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Stefan Kangas Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 30 Dec 2020 12:08:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 44858 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 44858-submit@debbugs.gnu.org id=B44858.16093300422447 (code B ref 44858); Wed, 30 Dec 2020 12:08:01 +0000 Original-Received: (at 44858) by debbugs.gnu.org; 30 Dec 2020 12:07:22 +0000 Original-Received: from localhost ([127.0.0.1]:42048 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kuaGA-0000dP-0r for submit@debbugs.gnu.org; Wed, 30 Dec 2020 07:07:22 -0500 Original-Received: from mail-pl1-f178.google.com ([209.85.214.178]:35236) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kuaG8-0000dB-OU for 44858@debbugs.gnu.org; Wed, 30 Dec 2020 07:07:21 -0500 Original-Received: by mail-pl1-f178.google.com with SMTP id g3so8607757plp.2 for <44858@debbugs.gnu.org>; Wed, 30 Dec 2020 04:07:20 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:in-reply-to:references:mime-version:date :message-id:subject:to:cc; bh=awYN39O/NhlpUXcOJGleWaoarP/MF3poi+uhrQAkCgw=; b=A1wI1F4DD97vgXKL7EGDaz4Wj8xkFfljo654Sy+o1IpXLZichzbBhl7QDzFpaBR1Pu LymbLJdJHbb2t6UHasowCOlZAEbhqxile+ebkbIAoYequ4etLjasjFmFNvPQChVKrQmQ ZQR1+lAYtVVULcmXxK6Ryt+X51Q42QFj/hDuwHg35nw/9BX53PpArct7MilMcMnRf364 UR6J7UrTRsuMi91rPGczbJtsQ8IMEsXuX0ySXYUtTA3qvXPSGFfipRFZhHaP6ioNabvF Rvj5fAtwjzWpgZUB2eBUtlFdjCuwwdfQusSZgWfzRPzfehaT2rhsOyLiB7fOY/aPYxb3 5VyA== X-Gm-Message-State: AOAM533e4GOSVl1xpY5YXXjtLUKk8hHKVeqCIQW2V+Jm5eDlpdxymiMt M6exRGum+2jroM3hpxJC3joBpSdKYYBJ+1xs/bg= X-Google-Smtp-Source: ABdhPJz1PfFcvTKclolcnj2knB8MAjvGUZlmEgZ4A00ihS0LnYQ3vo2kgSrE8potqOkdOdR6vXf+PY7P2wCRaMzMNdI= X-Received: by 2002:a17:902:9309:b029:db:c725:d19c with SMTP id bc9-20020a1709029309b02900dbc725d19cmr31705494plb.39.1609330034993; Wed, 30 Dec 2020 04:07:14 -0800 (PST) Original-Received: from 753933720722 named unknown by gmailapi.google.com with HTTPREST; Wed, 30 Dec 2020 04:07:14 -0800 In-Reply-To: <87v9dss2ic.fsf@gnus.org> X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:197021 Archived-At: Lars Ingebrigtsen writes: > Stefan Kangas writes: > >> The problem I saw was basically warnings >> about symbols only visible after macro expansion, and that warnings >> would point to entirely the wrong line and column. > > Oh, OK, the problem was in the lines/column output, not with detecting > the doc strings themselves? > > Yes, that sounds like a problem, but... I think we can live with > inaccurate lines here. So I tried enabling warnings also for lambda's and here is a fairly exhaustive list of things that leads to problems: 1. cl-defun In auth-source-netrc-search: auth-source.el:1224:11: Warning: docstring wider than 80 characters Here, the offending line is this autogenerated line: (fn &rest SPEC &key BACKEND REQUIRE CREATE TYPE MAX HOST USER PORT &allow-other-keys) 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 "^([^)])$"? 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? 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. 4. semantic These macros results in wide docstrings in some cases: - define-overloadable-function - define-semantic-decoration-style - define-mode-local-override 5. define-derived-mode Finally, we have some remaining cases where define-derived-mode leads to wide docstrings, e.g.: In newsticker-treeview-list-mode: net/newst-treeview.el:2031:52: Warning: docstring wider than 80 characters These should be easy to fix, and I already have an idea for how.