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#72357: Checkdoc fixes in transient.el Date: Sat, 14 Sep 2024 06:40:58 -0700 Message-ID: References: <87a5hzn9qn.fsf@bernoul.li> 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="28350"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 72357@debbugs.gnu.org To: Jonas Bernoulli Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Sat Sep 14 15:43:24 2024 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 1spT3c-0007Bu-2r for geb-bug-gnu-emacs@m.gmane-mx.org; Sat, 14 Sep 2024 15:43:24 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1spT39-0006hs-9k; Sat, 14 Sep 2024 09:42:55 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1spT37-0006hS-1R for bug-gnu-emacs@gnu.org; Sat, 14 Sep 2024 09:42:53 -0400 Original-Received: from debbugs.gnu.org ([2001:470:142:5::43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1spT35-0005JV-Um for bug-gnu-emacs@gnu.org; Sat, 14 Sep 2024 09:42:52 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=debbugs.gnu.org; s=debbugs-gnu-org; h=Date:MIME-Version:References:In-Reply-To:From:To:Subject; bh=TJiXi2GpE5DDvCdsZOXUtCT5TYD29U/mkprFx4ri1mk=; b=V4axo1t/gWy6Zp+Imw19FsNT1UftFnd/6gIobo3OqbGh/aymEPHQC1pMCb9onPEI+MgiCkGXZg+y1yArg8YorpDYRwHR47Q8n1ltCf879ptqQnJdHZGQp5ap9WGf7oSiiY3dzhVEbZIlh99Wx1188Vo9GQNBnxWEgqj08dbdHM/AqI6aCmPjjobx9COv3+oq7OeXpSoWSXT/BhB7swDc4gEpV1rH3LcrYx6T7Ktid5YfYWkoksgkkc4t+QsXa6WV4konqrN5EEtTb/QsXg1DWND18zRgg1bHc73kFmhFZmtdkRnnaHNCczduEHcsv00zZL/qo5/r4rIVixYCpGbZIA==; Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1spT3G-0006zK-5G for bug-gnu-emacs@gnu.org; Sat, 14 Sep 2024 09:43:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Stefan Kangas Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 14 Sep 2024 13:43:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 72357 X-GNU-PR-Package: emacs Original-Received: via spool by 72357-submit@debbugs.gnu.org id=B72357.172632133726774 (code B ref 72357); Sat, 14 Sep 2024 13:43:02 +0000 Original-Received: (at 72357) by debbugs.gnu.org; 14 Sep 2024 13:42:17 +0000 Original-Received: from localhost ([127.0.0.1]:45143 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1spT2W-0006xm-U8 for submit@debbugs.gnu.org; Sat, 14 Sep 2024 09:42:17 -0400 Original-Received: from mail-ej1-f46.google.com ([209.85.218.46]:53688) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1spT2V-0006xU-Bp for 72357@debbugs.gnu.org; Sat, 14 Sep 2024 09:42:16 -0400 Original-Received: by mail-ej1-f46.google.com with SMTP id a640c23a62f3a-a8a7903cb7dso128297666b.3 for <72357@debbugs.gnu.org>; Sat, 14 Sep 2024 06:42:04 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1726321259; x=1726926059; darn=debbugs.gnu.org; h=cc:to:subject:message-id:date:mime-version:references:in-reply-to :from:from:to:cc:subject:date:message-id:reply-to; bh=TJiXi2GpE5DDvCdsZOXUtCT5TYD29U/mkprFx4ri1mk=; b=bQ8Nj0lm/nV4HreTdFLsHQOnE1e164PXpZysTxWwRo0oLTWP4TcnEeGU/kZTzzmUky PNMLb2c489vr66FOQFRG4FETwCUtnraKHDnQZbE5omhu4hSHF1s1TxJHhGc2X2A8YN5U RAg6TeHGVV7vatK9MWkzz0Z8BXfN5AfkkbZ6G0WXX45aXf714wq5daoA/wmqqtAK8UU5 oKFZeAy/fuTEhp5m3wTPb7rbBWY+29WLgulvNHZ7VHFk2rFYnz8AHHdEECkvOIrUDo8h N3DsPU13aSkFkrewMYXLFRpedjCfT1RDv9/M56+Noc7PutCtXIbemVpL9i0RGytMN/iT yvjw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1726321259; x=1726926059; h=cc:to:subject:message-id:date:mime-version:references:in-reply-to :from:x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=TJiXi2GpE5DDvCdsZOXUtCT5TYD29U/mkprFx4ri1mk=; b=uO/AAhiP9v13kwOG/9ZiJTSOusJ049xiTOYliT4FQNfNa18tIIDX1XzHHlgAf4NH6E xRo72GXh+mqFx+C93CpZ2gXt+aFLUTpjtWrMYb7rx/EsK8WWV3LoAcSTrMKGdhXRG6s1 4RH2jdVrsIwyMROk8lGmAPBy5nuImgGpREPEulFloCnqFlYlM0ceemnfouLgWDgkGJmM TKk+jf1juITg5cHkMy8mdfUQUbJAIFOsJ/uy20d3fe9qXLrvk21GfDmmDHW5wrexFjfp 4aLInd27bEE2w3GulSM/e4PzS2jwK59Xhn88g/LjedDnWYleG+hNVpU61OkJa0OF+6Gy KmQg== X-Gm-Message-State: AOJu0YySCshsuTo5fLdNaPgXb1TOuoWdVNo1ZSdCqHCz3vfTmkrJGD45 6CWF0qZIFYUtUAMhQGfW/c9l5ZgN8SdR60kAHe/pggblE0BPobwMdijONv3WTyNrWOOs0pVugXW x7KFKqxEv5F6uHwgUCftwYtyrvIuqJ3p4mkw= X-Google-Smtp-Source: AGHT+IHNtQiHiPtf+3F57qem4zSIsQDdK1CvwJ8aCgxecYeL9klw+q8tbNEg3FfgwcSTdd/tSqFWnaLr8TqOzNU61o4= X-Received: by 2002:a05:6402:5108:b0:5c2:6311:c9d1 with SMTP id 4fb4d7f45d1cf-5c41e1b5325mr7619322a12.22.1726321258833; Sat, 14 Sep 2024 06:40:58 -0700 (PDT) Original-Received: from 753933720722 named unknown by gmailapi.google.com with HTTPREST; Sat, 14 Sep 2024 06:40:58 -0700 In-Reply-To: <87a5hzn9qn.fsf@bernoul.li> 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-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.bugs:291747 Archived-At: Jonas Bernoulli writes: > Looking at, for example, "C-h f transient-format-description", I feel > that it would not make sense if all the methods themselves began with a > summary line. Only the overall generic function *needs* a summary line. > In some case it may make sense to give individual methods their own > summary lines, but for very short, one paragraph method docstrings this > should not be a requirements. When a method is so simple that it can be > described using a single short paragraph (but not a single sentence, > which can fit on a single line), then that should be possible, without > being forced to mess up the justification of that paragraph. Sure, I understand your reasoning. I don't know if this needs pointing out, but do feel free to revert these changes. Meanwhile, Eli has proposed a rewording of the docstring that you might want to look at. > IMO checkdoc should be updated to not enforce the conventions, which > were designed for "top-level" functions (and variables) on methods > as well. Makes sense to me. BTW, with debbugs, it's better to put people in the "X-Debbugs-CC" header than "Cc". That way, I get the email forwarded to me by the bug tracker, and when I hit "wide reply", I send it to the right bug automatically (I had to edit in manually here).