From unknown Wed Jul 16 00:58:11 2025 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 X-Mailer: MIME-tools 5.509 (Entity 5.509) Content-Type: text/plain; charset=utf-8 From: bug#77124 <77124@debbugs.gnu.org> To: bug#77124 <77124@debbugs.gnu.org> Subject: Status: [PATCH] Optionally display function docstring in eldoc Reply-To: bug#77124 <77124@debbugs.gnu.org> Date: Wed, 16 Jul 2025 07:58:11 +0000 retitle 77124 [PATCH] Optionally display function docstring in eldoc reassign 77124 emacs submitter 77124 Elijah Gabe P=C3=A9rez severity 77124 wishlist tag 77124 patch thanks From debbugs-submit-bounces@debbugs.gnu.org Wed Mar 19 14:32:46 2025 Received: (at submit) by debbugs.gnu.org; 19 Mar 2025 18:32:46 +0000 Received: from localhost ([127.0.0.1]:53069 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tuyDd-0001lD-Fj for submit@debbugs.gnu.org; Wed, 19 Mar 2025 14:32:45 -0400 Received: from lists.gnu.org ([2001:470:142::17]:53300) by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.84_2) (envelope-from ) id 1tuyDY-0001kv-Sb for submit@debbugs.gnu.org; Wed, 19 Mar 2025 14:32:43 -0400 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 1tuyDG-0002Vx-1h for bug-gnu-emacs@gnu.org; Wed, 19 Mar 2025 14:32:24 -0400 Received: from mail-ot1-x343.google.com ([2607:f8b0:4864:20::343]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1tuyDD-0001Ti-Em for bug-gnu-emacs@gnu.org; Wed, 19 Mar 2025 14:32:21 -0400 Received: by mail-ot1-x343.google.com with SMTP id 46e09a7af769-72bbd3a3928so2920972a34.2 for ; Wed, 19 Mar 2025 11:32:18 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1742409137; x=1743013937; darn=gnu.org; h=mime-version:message-id:date:subject:to:from:from:to:cc:subject :date:message-id:reply-to; bh=GlJlD/aOof5emWJ6FhIF6xisIE+mh6llrVCVin+08Cw=; b=LhTQoFoNsNQYJ+xLfnbv1zpQEFOWVpK+YNr27Rx/BqGmWmrTrN+VNrLPp1AVy3PS4/ BNC0F9vyv5+5fugdforFfowffA5W/30l5nhJjW1Janj6IGKoUKd7aHGtiU76L4rZSUoT iSgKDn580ygjzoYMfI9dNXkoWVaoYZJyUGiibdvsXdLJMPRc/CQQR00iFUe5UdN0vrk4 S0NNsKCbhpbEK7iLR7k5wG7BDKB3XOwUrcdyBvh+1yxYe6t+9/GTgHFAG8unLrv/7XcE TP8fvdOjZYk/wGIeQttyXwj3BYN6zWXbviEsB0YIFjV+VDMq8McijxUS2/eCZPJ4HF6p +iVA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1742409137; x=1743013937; h=mime-version:message-id:date:subject:to:from:x-gm-message-state :from:to:cc:subject:date:message-id:reply-to; bh=GlJlD/aOof5emWJ6FhIF6xisIE+mh6llrVCVin+08Cw=; b=wSyQWlZsUo9sZI+yMXo2IlQVAQg03HQF3LEY+BdXcFxPFN0fRcSrLTcDu1Naxi3taq aGy5OOTA7MPkn2a/RfUd1cciTVhisittmTDCraj/ZIUmqX+Id7uxaHln9kDs7HuAk6w5 cIHkK89RRX8psqtynLB8avcMFZweMwbig3ECyq43FxYRmerdPCtQTGtW2uAMr6nq+SbK jJQa2CPYwcqlulfGLoo1OQYdRydSZox5TUsaiA9ZhcvqtnfKKhqu0ySMQr1QyG30cs8p Su3sOBOplwMFH/oUKfeFiLVMh68F/tcew0oq/cWo7V8Qh5OVIHKLA3h9i51CNfX3+ldw E0dA== X-Gm-Message-State: AOJu0Yy0zoKmBqGb6DjotX4P6bfrpuKgZAL4GiCTQBcTJnWLzuUsoaYi iALbYj9R7y/f3gXad26SXgm54tvVuwdwfaZCCXZjohDxL3lCHyJ4deYAldQt X-Gm-Gg: ASbGncve6EIkvIl71zvr2haFnnc2TsPF2KtcNV9lzo69UwDVOQQYtn8iz85plR2zsnt bnSGngC7eJi8lRduXZYNdnyHSoYHE/OhcGDWI6Fz3P2l4aQ3jxHSMOAEkZpJl1Ttg1/kHE1CsP3 uNTNEfAOn/7526Jd/74cblpPMej4gjXjHbn/VGiMVqCQ2aJiKol5gVN4yDVRS8z2Ac60Ts+3qBv 0bLAM009+hCT7LL3cIfebQdcYUid6h0oG8LCa2EBlgwpkHPUhiO9Qd/1JjdpncVsdYL39/w+xZW mj1YFNZknE2J X-Google-Smtp-Source: AGHT+IF4TkloXdIhRFTCTvnNaCloaeyXpCv/ygSyYxN5HOG0+VxnojLSCVfyV3lAokkh83mqgcS72A== X-Received: by 2002:a05:6830:640a:b0:727:3664:ca28 with SMTP id 46e09a7af769-72c02d77a98mr503756a34.0.1742409137083; Wed, 19 Mar 2025 11:32:17 -0700 (PDT) Received: from fedora ([2806:10ae:e:622a::3]) by smtp.gmail.com with ESMTPSA id 46e09a7af769-72bb26bb82dsm2560323a34.32.2025.03.19.11.32.16 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 19 Mar 2025 11:32:16 -0700 (PDT) From: =?utf-8?Q?Elijah_Gabe_P=C3=A9rez?= To: bug-gnu-emacs@gnu.org Subject: [PATCH] Optionally display function docstring in eldoc X-Debbugs-Cc: Date: Wed, 19 Mar 2025 12:32:15 -0600 Message-ID: <871pus50sw.fsf@gmail.com> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Received-SPF: pass client-ip=2607:f8b0:4864:20::343; envelope-from=eg642616@gmail.com; helo=mail-ot1-x343.google.com X-Spam_score_int: -15 X-Spam_score: -1.6 X-Spam_bar: - X-Spam_report: (-1.6 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_ENVFROM_END_DIGIT=0.25, FREEMAIL_FROM=0.001, HTML_MESSAGE=0.001, HTML_OBFUSCATE_05_10=0.26, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-Spam-Score: 1.2 (+) X-Spam-Report: Spam detection software, running on the system "debbugs.gnu.org", has NOT identified this incoming email as spam. The original message has been attached to this so you can view it or label similar future email. If you have any questions, see the administrator of that system for details. Content preview: Tags: patch This user option tell whether 'eldoc' should display elisp function docstring. If set to 'short' only display a short docstring, otherwise if set to 'full', display full docstring. If set to nil do no [...] Content analysis details: (1.2 points, 10.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- 1.0 SPF_SOFTFAIL SPF: sender does not match SPF record (softfail) 0.2 FREEMAIL_ENVFROM_END_DIGIT Envelope-from freemail username ends in digit (eg642616[at]gmail.com) -0.0 SPF_HELO_PASS SPF: HELO matches SPF record 0.0 FREEMAIL_FROM Sender email is commonly abused enduser mail provider (eg642616[at]gmail.com) 0.0 HTML_OBFUSCATE_05_10 BODY: Message is 5% to 10% HTML obfuscation 0.0 HTML_MESSAGE BODY: HTML included in message -0.0 RCVD_IN_DNSWL_NONE RBL: Sender listed at https://www.dnswl.org/, no trust [2001:470:142:0:0:0:0:17 listed in] [list.dnswl.org] X-Debbugs-Envelope-To: submit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: 0.2 (/) --=-=-= Content-Type: multipart/alternative; boundary="==-=-=" --==-=-= Content-Type: text/plain Tags: patch This user option tell whether 'eldoc' should display elisp function docstring. If set to 'short' only display a short docstring, otherwise if set to 'full', display full docstring. If set to nil do not show function docstring. In GNU Emacs 31.0.50 (build 1, x86_64-redhat-linux-gnu, GTK+ Version 3.24.43, cairo version 1.18.2) of 2025-03-18 built on 0dae0d7b05b64c3db75f27d2c3f0cd33 System Description: Fedora Linux 41 (Workstation Edition) --==-=-= Content-Type: text/html

Tags: patch

This user option tell whether 'eldoc' should display elisp function docstring.
If set to 'short' only display a short docstring, otherwise if set to
'full', display full docstring.
If set to nil do not show function docstring.

In GNU Emacs 31.0.50 (build 1, x8664-redhat-linux-gnu, GTK+ Version
3.24.43, cairo version 1.18.2) of 2025-03-18 built on
0dae0d7b05b64c3db75f27d2c3f0cd33
System Description: Fedora Linux 41 (Workstation Edition)

--==-=-=-- --=-=-= Content-Type: text/patch Content-Disposition: attachment; filename=0001-Optionally-display-function-docstring-in-eldoc.patch >From 1b97cd0dff054c862e81434f1376109bb9d30c66 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?El=C3=ADas=20Gabriel=20P=C3=A9rez?= Date: Wed, 19 Mar 2025 12:01:22 -0600 Subject: [PATCH] Optionally display function docstring in eldoc Allow display (optionally) function docstring in eldoc. * etc/NEWS: Announce changes. * lisp/progmodes/elisp-mode.el (elisp-eldoc-var-docstring-with-value): New user option. (elisp-get-fnsym-args-string): Display function docstring. --- etc/NEWS | 7 +++++++ lisp/progmodes/elisp-mode.el | 24 ++++++++++++++++++++++-- 2 files changed, 29 insertions(+), 2 deletions(-) diff --git a/etc/NEWS b/etc/NEWS index 0797fc03217..b0a0e6cb6a3 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -1900,6 +1900,13 @@ another pattern matching syntax that is different from that of 'pcase', which some users might find less cryptic. See the Info node "(elisp) cond* Macro" for details. +--- +** New user option 'elisp-eldoc-show-function-docstring'. +This user option tell whether 'eldoc' should display function docstring. +If set to 'short' only display a short docstring, otherwise if set to +'full', display full docstring. +If set to nil do not show function docstring. + --- ** New function 'shell-command-do-open'. This lets a Lisp program access the core functionality of the diff --git a/lisp/progmodes/elisp-mode.el b/lisp/progmodes/elisp-mode.el index a34f29bffea..761d392be63 100644 --- a/lisp/progmodes/elisp-mode.el +++ b/lisp/progmodes/elisp-mode.el @@ -1882,6 +1882,17 @@ elisp-eldoc-var-docstring-with-value (format "[%sc more]" more))))) :thing cs :face 'font-lock-variable-name-face)))) +(defcustom elisp-eldoc-show-function-docstring nil + "Show function docstring in `eldoc-mode'. +If set to `short' only display a short docstring, otherwise if set to +`full', display full docstring. + +If set to nil do not show function docstring." + :type '(choice + (const :tag "None") + (const :tag "Short" short) + (const :tag "Full" full)) + :group 'elisp) (defun elisp-get-fnsym-args-string (sym &optional index) "Return a string containing the parameter list of the function SYM. @@ -1908,8 +1919,17 @@ elisp-get-fnsym-args-string (substitute-command-keys (car doc))) (t (help-function-arglist sym))))) ;; Stringify, and store before highlighting, downcasing, etc. - (elisp--last-data-store sym (elisp-function-argstring args) - 'function)))))) + (elisp--last-data-store + sym + (concat (elisp-function-argstring args) + (pcase elisp-eldoc-show-function-docstring + ('full + (concat "\n" (cdr doc))) + ('short + (save-match-data + (when (string-match "\\." (cdr doc)) + (concat "\n" (substring (cdr doc) 0 (match-end 0)))))))) + 'function)))))) ;; Highlight (if argstring (elisp--highlight-function-argument -- 2.48.1 --=-=-= Content-Type: text/plain -- - E.G via GNU Emacs and Org. --=-=-=-- From debbugs-submit-bounces@debbugs.gnu.org Wed Mar 19 16:54:48 2025 Received: (at control) by debbugs.gnu.org; 19 Mar 2025 20:54:48 +0000 Received: from localhost ([127.0.0.1]:53413 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tv0R6-0003PQ-3e for submit@debbugs.gnu.org; Wed, 19 Mar 2025 16:54:48 -0400 Received: from mail-ed1-x531.google.com ([2a00:1450:4864:20::531]:42481) by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.84_2) (envelope-from ) id 1tv0R2-0003P2-2n for control@debbugs.gnu.org; Wed, 19 Mar 2025 16:54:44 -0400 Received: by mail-ed1-x531.google.com with SMTP id 4fb4d7f45d1cf-5e614da8615so166495a12.1 for ; Wed, 19 Mar 2025 13:54:44 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1742417678; x=1743022478; darn=debbugs.gnu.org; h=to:subject:message-id:date:mime-version:from:from:to:cc:subject :date:message-id:reply-to; bh=rsPECPhBF9ikGz3o8JNM4KghZSvGybzyETNna6qKICw=; b=EQ7BfNWf5qxCV2PXEFTvT+GzKsfB3ahTEOo06Zk+rAp0DUZCxPuZKY4CidUWmKJr00 FNYO3KKrnUF5hUPwSypXkQS0sNQ9uiIR7IakQkAt+nAKObLTKQOv8Zu+geQLeanz7/Wb jLrbyxxmEt88bZzpdzcE0kBSvIUqG6YauUWdQ0E/vYIE5cYhGOO1FfouPtc24RHojU+9 rNTY1p/0s1s2dIg99W8/0siX1NgyHvkXStezeEvr3YQjxDJhvGjq4EkFE0ib4nyNjZ1a EoV0l/naHewp3H/nvchNTW6GLwGtFFrxhGHK271vJ2JVDMkJiZWhB8CgpJ6DEqNXV0jY 8zDw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1742417678; x=1743022478; h=to:subject:message-id:date:mime-version:from:x-gm-message-state :from:to:cc:subject:date:message-id:reply-to; bh=rsPECPhBF9ikGz3o8JNM4KghZSvGybzyETNna6qKICw=; b=cS/AleiaYqMxmjgumesSNdUJJ13UhWJFBIMaLwJ8U3DxB0eitwVduCkur9lbKIMMQ0 26IkXYeH0R5EYrqxQ0zRV/djxEWe8yBrfMPjZBmkOfUUZGEqkrwUTxLndAFanMw5jVB8 FKzaEVKEvsHFnfJLDHGgpK6w1ZMdhg6Llu/YDb2tAK3/CIlbCzBjJwXYmGRw9v28+T3e M8MiPRqBOXl3Q0/W+aaX+lIkfpTZX+6jZtASZcILIFdpmi5aStt+ayoL8L3obJIVO0zS jagYLhg0BacWI+MfZSv5q+cWTacdp8Dnw9nPJpGpc8KUQJfSuvjSc11x/SpIIuXXiNPl z1/g== X-Gm-Message-State: AOJu0YzNevQYJSBcq6QTTRNLrAjXpCVMHesdJVSVkzFWYk30yN0lVmyV 6Cjfzj17DXU1NWIxT6EmtC51xVWmD802IPXxgJtK09HVoL/3CZy6VYUhpFvyC4wKTrF8S/TuCAm T8bsgAnLdFG002xDXwmgOYxWYRHL7s1XV X-Gm-Gg: ASbGncvAmkG7T84sgqHgv1+Clc16nV9x8S+IlUvfojxoXsiCOhNCI8rt9Aiq7dQvB4J uWUCyl3Zm0Xu4kRl2xlrd4s8J2sR0vlvpzHNblMCteW4rA6Bc96CUz+Y9Uv+D/m6f+FG/tPUHfZ M1UnE1GYgcsaA3WlEaEylYgoKJpVw= X-Google-Smtp-Source: AGHT+IHzQ4kAfcNvAUHZjmrg4o4N/xBjwxlsSndSNayDQlucqUD4wPvBB3b/aCtG+lLMupFZbcPWZnnm++5UR5ctQ4o= X-Received: by 2002:a05:6402:358f:b0:5de:d932:a54c with SMTP id 4fb4d7f45d1cf-5eb996fe439mr1242265a12.2.1742417677784; Wed, 19 Mar 2025 13:54:37 -0700 (PDT) Received: from 753933720722 named unknown by gmailapi.google.com with HTTPREST; Wed, 19 Mar 2025 13:54:37 -0700 From: Stefan Kangas MIME-Version: 1.0 Date: Wed, 19 Mar 2025 13:54:37 -0700 X-Gm-Features: AQ5f1Jr8E0Gt6pg2YG_DP3YJfAnZm6GE2a_3Ia4xEL4sMZr4CaoYnBimYD_U5co Message-ID: Subject: control message for bug #77124 To: control@debbugs.gnu.org Content-Type: text/plain; charset="UTF-8" X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: control X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) severity 77124 wishlist quit From debbugs-submit-bounces@debbugs.gnu.org Thu Mar 20 08:26:03 2025 Received: (at 77124) by debbugs.gnu.org; 20 Mar 2025 12:26:03 +0000 Received: from localhost ([127.0.0.1]:55975 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tvEyI-0003Jk-Kz for submit@debbugs.gnu.org; Thu, 20 Mar 2025 08:26:03 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:60272) by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.84_2) (envelope-from ) id 1tvEyE-0003JD-LW for 77124@debbugs.gnu.org; Thu, 20 Mar 2025 08:25:59 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tvEy9-0006oD-6U; Thu, 20 Mar 2025 08:25:53 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-version:References:Subject:In-Reply-To:To:From: Date; bh=PeJtgVZXKIEz06q1sSRtb2z/3fSqStHJ3npSU5azZro=; b=POYtwBBuQsAML2hJ4RF1 VeC+Y7Gsw7aZ3wdT8XZlyp3StUHfhaOvXOwKd2vsghHZiSaFIMwnA4q4FymDBt7FBYtEpVwE3BwpD PY66ElfOc4mWnFf0nPk56YtMPdbKYAekG3wcGkpwc4Qzs0bYZCQDIXGgMwihA+r6SULtspUwmka3+ ugwhPvmhgiOhuhdHobzT6+baJ+0dhiK3zaQWvjgEN3UUyObZJVsWpotlWovMbtIsW9XiAziwlgK36 k407PFYBXMqvxVPx1bvAE9TcPo/+aLnF+ar5OO18K9z49VmqlQqNZdP9KT+0j4O55QsDimp4mF/t3 kaEehz47SbPsXQ==; Date: Thu, 20 Mar 2025 14:25:45 +0200 Message-Id: <86zfhfnb1y.fsf@gnu.org> From: Eli Zaretskii To: Elijah Gabe =?utf-8?Q?P=C3=A9rez?= In-Reply-To: <871pus50sw.fsf@gmail.com> (message from Elijah Gabe =?utf-8?Q?P=C3=A9rez?= on Wed, 19 Mar 2025 12:32:15 -0600) Subject: Re: bug#77124: [PATCH] Optionally display function docstring in eldoc References: <871pus50sw.fsf@gmail.com> MIME-version: 1.0 Content-type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 77124 Cc: 77124@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Elijah Gabe Pérez > Date: Wed, 19 Mar 2025 12:32:15 -0600 > > This user option tell whether 'eldoc' should display elisp function docstring. > If set to 'short' only display a short docstring, otherwise if set to > 'full', display full docstring. > If set to nil do not show function docstring. Where will the doc string be shown? If in the echo-area, then what will happen when eldoc shows the info on the mode line instead? > +(defcustom elisp-eldoc-show-function-docstring nil > + "Show function docstring in `eldoc-mode'. > +If set to `short' only display a short docstring, otherwise if set to > +`full', display full docstring. This should explain what is the "short docstring". Also, where the documentation is shown. > +If set to nil do not show function docstring." > + :type '(choice > + (const :tag "None") > + (const :tag "Short" short) > + (const :tag "Full" full)) > + :group 'elisp) The :version tag is missing. Thanks. P.S. For the next version of the patch, please remember mentioning the bug number in the commit log message. From debbugs-submit-bounces@debbugs.gnu.org Thu Mar 20 14:37:40 2025 Received: (at 77124) by debbugs.gnu.org; 20 Mar 2025 18:37:41 +0000 Received: from localhost ([127.0.0.1]:58950 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tvKlt-0006BL-5S for submit@debbugs.gnu.org; Thu, 20 Mar 2025 14:37:40 -0400 Received: from mail-oa1-x42.google.com ([2001:4860:4864:20::42]:61515) by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.84_2) (envelope-from ) id 1tvKln-00069Z-LW for 77124@debbugs.gnu.org; Thu, 20 Mar 2025 14:37:34 -0400 Received: by mail-oa1-x42.google.com with SMTP id 586e51a60fabf-2a01bcd0143so1268834fac.2 for <77124@debbugs.gnu.org>; Thu, 20 Mar 2025 11:37:31 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1742495846; x=1743100646; darn=debbugs.gnu.org; h=mime-version:user-agent:message-id:date:references:in-reply-to :subject:cc:to:from:from:to:cc:subject:date:message-id:reply-to; bh=L/ylrvFbmP2ZmrQU+HvDW/9LQ8ESiDH5GYa7mt/YzD0=; b=PB9OFE5ZLe7msa7nuHFLGxgWpckkpRiHXDwEbrnJT4PJGIpSh+zjYTuESdaMCPAWet SSkruHFHamqLaQRINghaSN7/LXmxIYGaNkz+p5at637seWNG/7KJvpt8xDLLi7qTxINM xKGbd4kMbvvh4S8G5Q4a9Wq+YJcEMnWYuSLlM6IbQdEVjZ7J8RSHGYiBNhPHIysZwdpA hPAXcCoa/exBihtFgmuVTridXw+uELbJpKNuIrLYc8Uoxf2JHNlh5mqLCJT6HmBVwwQy 6U5VgTCC4VAZr+Crdtf7AjECZBf0+CbcvMo6KRvbyUnMJ38uP8/CVWrESq9X45ygzgcP vIAw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1742495846; x=1743100646; h=mime-version:user-agent:message-id:date:references:in-reply-to :subject:cc:to:from:x-gm-message-state:from:to:cc:subject:date :message-id:reply-to; bh=L/ylrvFbmP2ZmrQU+HvDW/9LQ8ESiDH5GYa7mt/YzD0=; b=hNyOsDpBnBiz6BqmIZe7c2hb/7vzXO+O7d+7SYPTmJeY6+o4hf5ylxNOdWmVlACPfe aLEI4I2TtrxXrv4Qs8QH76cw3jFE5w+GJjUCLln785ig8i7/p8htX/0WQlvOGx4JzPWc 8E+uIB7CGpBTTtdAmqH6HKLzxr0Ro0/faeNDRkmXyiaSVA6GNmwjgvvTL+s5gGYlZst0 lOQ4gSLPBx+p6JNOhHwno7jjsvrGy87K8G7mrD/K9CWUkxqdq/SYlDLWQv8LtIHA5bia j5YaS28DxeA9XItC4Nr7exf2GNH2P0Xs85QsmdU+1+05IaNgagC274onQ+JIq0Fl3siB KkWg== X-Gm-Message-State: AOJu0Yw+RTopvFzBTduuKXfdjY8QaygnsiQRgpkuhVUfI23dI7ODJWAw 9Ihc3WllPCy+LfW3+YfJhhdPHhVe2tplOT/ardeIlfkJSMIJVWywbmE/ydNd X-Gm-Gg: ASbGnctmIJOCoZAZrOwZap3cTFEQKmLBW6RNVlca5Y+rP1k420O7VMOIz8ogvqb4zOX iV2gqItZIffX/NTmTh+xgU+JMhKQtYzgYZ8fYQxNgyxBy1LPRqfr26YGLLsxT2RRwWYu3aJuW17 KAv3M3Rq2eAVuYjWAPlgSB1guXV4oBK9hE1h9knCLnzbFhulDf2ndaUlpVLb2J1ESGg5j0nLX/o 6C46CHS2Wm7xafxrZ5lRc78gYe4MSdRknHF7Iq7ZzfTAaDH1kg6SeRZKAzxy2Hsbm6UB7rpklg3 5n2yFsPMbqi2 X-Google-Smtp-Source: AGHT+IGEVSp09Lt5iT1dTg7PyP7K83D3OBxhavvPeS37RMSmE6F8F4Bx39rwyFJ/7GK/PuXJ0cw9tw== X-Received: by 2002:a05:6870:7d88:b0:2c1:44a9:fc16 with SMTP id 586e51a60fabf-2c78054a9afmr437900fac.38.1742495845214; Thu, 20 Mar 2025 11:37:25 -0700 (PDT) Received: from fedora ([2806:10ae:e:5fce::1]) by smtp.gmail.com with ESMTPSA id 586e51a60fabf-2c77ec52384sm83460fac.20.2025.03.20.11.37.24 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 20 Mar 2025 11:37:24 -0700 (PDT) From: =?utf-8?Q?Elijah_Gabe_P=C3=A9rez?= To: Eli Zaretskii Subject: Re: bug#77124: [PATCH] Optionally display function docstring in eldoc In-Reply-To: <86zfhfnb1y.fsf@gnu.org> References: <871pus50sw.fsf@gmail.com> <86zfhfnb1y.fsf@gnu.org> Date: Thu, 20 Mar 2025 12:37:23 -0600 Message-ID: <87sen7h7ks.fsf@gmail.com> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/31.0.50 MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Spam-Score: 0.3 (/) X-Debbugs-Envelope-To: 77124 Cc: 77124@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -0.7 (/) --=-=-= Content-Type: multipart/alternative; boundary="==-=-=" --==-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Eli Zaretskii writes: >> From: Elijah Gabe P=C3=A9rez >> Date: Wed, 19 Mar 2025 12:32:15 -0600 >> This user option tell whether 'eldoc' should display elisp function docs= tring. >> If set to 'short' only display a short docstring, otherwise if set to >> 'full', display full docstring. >> If set to nil do not show function docstring. > Where will the doc string be shown? > If in the echo-area, then what will happen when eldoc shows the info > on the mode line instead? I've fixed it to only show in the echo-area and not to mode-line. Also I've moved it to a function instead modifying existing ones, similar to ~elisp-eldoc-var-docstring-with-value~. >> +(defcustom elisp-eldoc-show-function-docstring nil >> + "Show function docstring in `eldoc-mode'. >> +If set to `short' only display a short docstring, otherwise if set to >> +`full', display full docstring. > This should explain what is the "short docstring". Also, where the > documentation is shown. I've added it. To explain: Instead display this full docstring: Set each SYM to the value of its VAL. The symbols SYM are variables; they are literal (not evaluated). The values VAL are expressions; they are evaluated. Thus, (setq x (1+ y)) sets x to the value of (1+ y). The second VAL is not computed until after the first SYM is set, and so o= n; each VAL can use the new value of variables set earlier in the setq. The return value of the setq form is the value of the last VAL. Only display it like this: Set each SYM to the value of its VAL. > P.S. For the next version of the patch, please remember mentioning the > bug number in the commit log message. Sure. --==-=-= Content-Type: text/html; charset=utf-8 Content-Transfer-Encoding: quoted-printable

Eli Zaretskii <eliz@gnu.org> writes:

From: Elijah Gabe P=C3=A9rez <eg642616@gmail.com>
Date: Wed, 19 Mar 2025 12:32:15 -0600

This user option tell whether 'eldoc' should display elisp function do= cstring.
If set to 'short' only display a short docstring, otherwise if set to
'full', display full docstring.
If set to nil do not show function docstring.

Where will the doc string be shown?

If in the echo-area, then what will happen when eldoc shows the info on the mode line instead?

I've fixed it to only show in the echo-area and not to mode-line.

Also I've moved it to a function instead modifying existing ones,
similar to elisp-eldoc-var-docstring-with-value.

+(defcustom elisp-eldoc-show-function-docstring nil
+ "Show function docstring in `eldoc-mode'.
+If set to `short' only display a short docstring, otherwise if set to
+`full', display full docstring.

This should explain what is the "short docstring". Also, where the documentation is shown.

I've added it.

To explain:
Instead display this full docstring:

Set each SYM to the value of its VAL.

The symbols SYM are variables; they are literal (not evaluated).
The values VAL are expressions; they are evaluated.
Thus, (setq x (1+ y)) sets x to the value of (1+ y).
The second VAL is not computed until after the first SYM is set, and so on;=
each VAL can use the new value of variables set earlier in the setq.
The return value of the setq form is the value of the last VAL.

Only display it like this:

Set each SYM to the value of its VAL.

P.S. For the next version of the patch, please remember mentioning the=
bug number in the commit log message.

Sure.

--==-=-=-- --=-=-= Content-Type: text/x-patch Content-Disposition: attachment; filename=0001-Optionally-display-function-docstring-in-eldoc.patch >From 77591a6cc151718060af84f1e5684f1fcb932b5b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?El=C3=ADas=20Gabriel=20P=C3=A9rez?= Date: Wed, 19 Mar 2025 12:01:22 -0600 Subject: [PATCH] Optionally display function docstring in eldoc Allow display (optionally) function docstring in eldoc. (Bug#77124) * etc/NEWS: Document changes. * lisp/progmodes/elisp-mode.el (elisp-eldoc-funcall-with-docstring-lenght): New user option. (elisp-eldoc-funcall-with-docstring): New function. --- etc/NEWS | 11 ++++++++++ lisp/progmodes/elisp-mode.el | 42 ++++++++++++++++++++++++++++++++++++ 2 files changed, 53 insertions(+) diff --git a/etc/NEWS b/etc/NEWS index 0797fc03217..44c2b36adc9 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -1900,6 +1900,17 @@ another pattern matching syntax that is different from that of 'pcase', which some users might find less cryptic. See the Info node "(elisp) cond* Macro" for details. +--- +** New eldoc function 'elisp-eldoc-funcall-with-docstring'. +This function includes the current function docstring in eldoc echo area +and can be used as a more detailed alternative to 'elisp-eldoc-funcall'. + +** New user option 'elisp-eldoc-funcall-with-docstring-lenght'. +This user option specifies how long function docstring must be displayed +in 'elisp-eldoc-funcall-with-docstring'. If set to 'short' only display +cut docstring before period. Otherwise if set to 'full', display full +docstring.' + --- ** New function 'shell-command-do-open'. This lets a Lisp program access the core functionality of the diff --git a/lisp/progmodes/elisp-mode.el b/lisp/progmodes/elisp-mode.el index a34f29bffea..22e300ea685 100644 --- a/lisp/progmodes/elisp-mode.el +++ b/lisp/progmodes/elisp-mode.el @@ -1845,6 +1845,48 @@ elisp-eldoc-funcall 'font-lock-function-name-face 'font-lock-keyword-face))))) +(defcustom elisp-eldoc-funcall-with-docstring-lenght 'short + "Specify function docstring lenght in `elisp-eldoc-funcall-with-docstring'. +If set to `short' only display docstring before period., +Otherwise if set to `full', display full docstring." + :type '(choice + (const :tag "Short" short) + (const :tag "Full" full)) + :group 'elisp + :version 31) + +(defun elisp-eldoc-funcall-with-docstring (callback &rest _ignored) + "Document function call at point by calling CALLBACK. +Intended for `eldoc-documentation-functions' (which see). +Compared to `elisp-eldoc-funcall', this also includes the +current function docstring, docstring lenght depends on +`elisp-eldoc-funcall-with-docstring-lenght'." + (let* ((sym-info (elisp--fnsym-in-current-sexp)) + (fn-sym (car sym-info)) + (doc (when (fboundp fn-sym) + (propertize + (cdr (help-split-fundoc + (condition-case nil (documentation fn-sym t) + (invalid-function nil)) + fn-sym)) + 'face 'font-lock-doc-face)))) + (when fn-sym + (funcall callback + (concat (apply #'elisp-get-fnsym-args-string sym-info) + (when (and doc (not (minibufferp))) + (concat + "\n" + (pcase elisp-eldoc-funcall-with-docstring-lenght + ('full doc) + ('short + (save-match-data + (when (string-match "\\." doc) + (concat "\n" (substring doc 0 (match-end 0)))))))))) + :thing fn-sym + :face (if (functionp fn-sym) + 'font-lock-function-name-face + 'font-lock-keyword-face))))) + (defun elisp-eldoc-var-docstring (callback &rest _ignored) "Document variable at point by calling CALLBACK. Intended for `eldoc-documentation-functions' (which see). -- 2.48.1 --=-=-= Content-Type: text/plain -- - E.G via GNU Emacs and Org. --=-=-=-- From debbugs-submit-bounces@debbugs.gnu.org Sat Mar 29 07:45:06 2025 Received: (at 77124) by debbugs.gnu.org; 29 Mar 2025 11:45:06 +0000 Received: from localhost ([127.0.0.1]:57327 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tyUcb-0006R4-RT for submit@debbugs.gnu.org; Sat, 29 Mar 2025 07:45:06 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:49402) by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.84_2) (envelope-from ) id 1tyUcZ-0006Q4-Jc for 77124@debbugs.gnu.org; Sat, 29 Mar 2025 07:45:04 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tyUcU-0006cZ-8Z; Sat, 29 Mar 2025 07:44:58 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-version:References:Subject:In-Reply-To:To:From: Date; bh=D3M4Hzw4QnosZb0GgC3jxA0vH2n+wTds7EiaQ58qhjw=; b=RqjMkLyXYSoZYDOfw1n5 mu1KCTRLYmp+424hf8K+ry7B6BOluA0aZKuIseiFgdfpj/AAh+9CU6FIXvuUCH7piiDtabk7APnc2 7qQNvNXcfxR+WDbScpVKcHNkh5ac2bFJMbA7mULcv8c0dBIG5dIYP04YwcIlVAvcbnlSo6kVhhIMy pkFXSS3FHb+DLP4XBYtZ6tMyYT9VnIoEKnE+A5GCXGO67T4TayNS+xLpJhLKU9+I0eQHn/vCVUgFK wTNLWyINBR9eUbWIpWS+e1T8DOSzsNUyf3AsrYJrHZTI/F3Pl72Ro25Sq06kl47keVm42QA1GyjZs t4lU2oNM286iCg==; Date: Sat, 29 Mar 2025 14:44:55 +0300 Message-Id: <86msd46oy0.fsf@gnu.org> From: Eli Zaretskii To: Elijah Gabe =?utf-8?Q?P=C3=A9rez?= In-Reply-To: <87sen7h7ks.fsf@gmail.com> (message from Elijah Gabe =?utf-8?Q?P=C3=A9rez?= on Thu, 20 Mar 2025 12:37:23 -0600) Subject: Re: bug#77124: [PATCH] Optionally display function docstring in eldoc References: <871pus50sw.fsf@gmail.com> <86zfhfnb1y.fsf@gnu.org> <87sen7h7ks.fsf@gmail.com> MIME-version: 1.0 Content-type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 77124 Cc: 77124@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Elijah Gabe Pérez > Cc: 77124@debbugs.gnu.org > Date: Thu, 20 Mar 2025 12:37:23 -0600 > > --- a/etc/NEWS > +++ b/etc/NEWS > @@ -1900,6 +1900,17 @@ another pattern matching syntax that is different from that of 'pcase', > which some users might find less cryptic. > See the Info node "(elisp) cond* Macro" for details. > > +--- > +** New eldoc function 'elisp-eldoc-funcall-with-docstring'. > +This function includes the current function docstring in eldoc echo area > +and can be used as a more detailed alternative to 'elisp-eldoc-funcall'. > + > +** New user option 'elisp-eldoc-funcall-with-docstring-lenght'. > +This user option specifies how long function docstring must be displayed > +in 'elisp-eldoc-funcall-with-docstring'. If set to 'short' only display > +cut docstring before period. Otherwise if set to 'full', display full > +docstring.' These two entries should be moved to a separate section "ElDoc" under "Changes in Specialized Modes and Packages in Emacs 31.1". Also, please mark the second entry with "---", and fix a typo there ("length"). > +(defcustom elisp-eldoc-funcall-with-docstring-lenght 'short > + "Specify function docstring lenght in `elisp-eldoc-funcall-with-docstring'. "Control length of doc string shown by `elisp-eldoc-funcall-with-docstring'." (Note the typo: "length".) > +If set to `short' only display docstring before period., ^ A comma is missing there. Also, there's a redundant comma at the end. And I would rephrase: If set to `short', only show the first sentence of the doc string. Thanks. From debbugs-submit-bounces@debbugs.gnu.org Sat Mar 29 15:35:30 2025 Received: (at 77124) by debbugs.gnu.org; 29 Mar 2025 19:35:30 +0000 Received: from localhost ([127.0.0.1]:33100 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tybxq-0004UJ-1K for submit@debbugs.gnu.org; Sat, 29 Mar 2025 15:35:30 -0400 Received: from mail-oi1-x243.google.com ([2607:f8b0:4864:20::243]:53418) by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.84_2) (envelope-from ) id 1tybxm-0004U3-GV for 77124@debbugs.gnu.org; Sat, 29 Mar 2025 15:35:28 -0400 Received: by mail-oi1-x243.google.com with SMTP id 5614622812f47-3fefbbc7dd4so1879196b6e.2 for <77124@debbugs.gnu.org>; Sat, 29 Mar 2025 12:35:26 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1743276920; x=1743881720; darn=debbugs.gnu.org; h=mime-version:user-agent:message-id:date:references:in-reply-to :subject:cc:to:from:from:to:cc:subject:date:message-id:reply-to; bh=08FyMb556qHaIxW5mCoB2C8r3pqAbHowd68xPdO2938=; b=IK+g9S8T32ikp1je5aoUU9FlB3mm+RhYRuESQ7eSr88+kh12VJOmHi6Pv3VSvYe5Pe Kd1NBjacrhdzgVo9tt5VxJ2u1jCZrwIOUIrU7GEaS8gGHC99U/NifEaLEDHP8CBMZGJV YaK0dW1NAMapSrzGRZaPOFkis0zQ7zMeDPhbcpbxMRYz8Q9Z135vYoOPEFL8ef5KxP3r vVVEVDoD6wl5FzyP6TYGEE3m+a3uCsehflumkRgAlv+0L6W0cWgNhmM1viV7KYxYaPoP iAqXawpqmtyCC1tjxZBnS4mRrki5vWeLN9n3XF8k17sOQSjZg+FuU2+GuvK/FlLMLWxw fD2w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1743276920; x=1743881720; h=mime-version:user-agent:message-id:date:references:in-reply-to :subject:cc:to:from:x-gm-message-state:from:to:cc:subject:date :message-id:reply-to; bh=08FyMb556qHaIxW5mCoB2C8r3pqAbHowd68xPdO2938=; b=Xos85acM+0KOa9OqEGw3EoSPHkRQD/xeLacMX5Pi1MVszcuEHre36nh5/msC35BJt0 e1x4WTQnW/T94VpAj4oPncfO16OWyIEzVhbt3JXFIhUbi+NVkcBNs0IhGfjyz7sXDQux d1RUHlTP3sg3sd6EQz4EZjYTjV1G/LQA3TGXjKbz1G26GGHw92GPOrWQjUD7TBegdbop MtP+mKVSW2wcaOuWDWh4CYcRNys8Pigai8K+Vq5mD7Nsqg0lUCFWbVPaRKq7QZFnAOxl YlI9uklRRSzUP+pXYZKcXAKxQqWSyyWts4VgXoAYfSIQSn2DthZhyDmMZcbaiEt6J66P FRSg== X-Gm-Message-State: AOJu0YwP8DR/qRW3TGT/Muqciu6wn8yW18NMuoPnT8ymNwmgfaJ/69Rf gtkHFj2Z/wJCA0//UUnQY/Ib3gt7z7p846il6plOzZf1s9l2cdrl0Q19VEO6 X-Gm-Gg: ASbGncvQcL6zzF9lbIKkt+9S7xAv5yp+lRwepr5KoygJEnG2bgMBjHCxb8zoj8x9Aqm u280ZqpL71cTwhk7l93T18NYpPwFci7sCRUfXNh99X6F9Nk/DIqlOTB5g+YIcxSV4QxgMmg740/ 7v0ZjAd7yXv2PrU8PJTkHg/18t7KK8CccWsqN8pTlPydOIVd4/xIvPA9ACyYDnEG1mGxSbkme5t 7kxHRfwnzShFPSCflSNRmU3tMvJ8Su7ijB83jumswcdVJqwN2mWx1nYggI7QHhgn6bzyrQm5JCM X8o8xpFHoEq9 X-Google-Smtp-Source: AGHT+IFomx7x/D29Ow82vm2glUNLegG6B3sMvS3jYN1gmScaHddNBppIb124pHLO8zNxY2wrvNAHrA== X-Received: by 2002:a05:6808:1895:b0:3fa:ca26:6291 with SMTP id 5614622812f47-3ff0f5cc296mr2510969b6e.28.1743276920202; Sat, 29 Mar 2025 12:35:20 -0700 (PDT) Received: from fedora ([2806:10ae:e:5fce::1]) by smtp.gmail.com with ESMTPSA id 5614622812f47-3ff051aa1f1sm812223b6e.22.2025.03.29.12.35.19 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sat, 29 Mar 2025 12:35:19 -0700 (PDT) From: =?utf-8?Q?Elijah_Gabe_P=C3=A9rez?= To: Eli Zaretskii Subject: Re: bug#77124: [PATCH] Optionally display function docstring in eldoc In-Reply-To: <86msd46oy0.fsf@gnu.org> References: <871pus50sw.fsf@gmail.com> <86zfhfnb1y.fsf@gnu.org> <87sen7h7ks.fsf@gmail.com> <86msd46oy0.fsf@gnu.org> Date: Sat, 29 Mar 2025 13:35:18 -0600 Message-ID: <87jz87pr49.fsf@gmail.com> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/31.0.50 MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Spam-Score: 0.3 (/) X-Debbugs-Envelope-To: 77124 Cc: 77124@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -0.7 (/) --=-=-= Content-Type: multipart/alternative; boundary="==-=-=" --==-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Eli Zaretskii writes: >> From: Elijah Gabe P=C3=A9rez >> Cc: 77124@debbugs.gnu.org >> Date: Thu, 20 Mar 2025 12:37:23 -0600 >> --- a/etc/NEWS >> +++ b/etc/NEWS >> @@ -1900,6 +1900,17 @@ another pattern matching syntax that is different= from that of 'pcase', >> which some users might find less cryptic. >> See the Info node "(elisp) cond* Macro" for details. >> +--- >> +** New eldoc function 'elisp-eldoc-funcall-with-docstring'. >> +This function includes the current function docstring in eldoc echo area >> +and can be used as a more detailed alternative to 'elisp-eldoc-funcall'. >> + >> +** New user option 'elisp-eldoc-funcall-with-docstring-lenght'. >> +This user option specifies how long function docstring must be displayed >> +in 'elisp-eldoc-funcall-with-docstring'. If set to 'short' only display >> +cut docstring before period. Otherwise if set to 'full', display full >> +docstring.' > These two entries should be moved to a separate section "ElDoc" under > "Changes in Specialized Modes and Packages in Emacs 31.1". > Also, please mark the second entry with "---", and fix a typo there > ("length"). >> +(defcustom elisp-eldoc-funcall-with-docstring-lenght 'short >> + "Specify function docstring lenght in `elisp-eldoc-funcall-with-docst= ring'. > "Control length of doc string shown by `elisp-eldoc-funcall-with-docstrin= g'." > (Note the typo: "length".) >> +If set to `short' only display docstring before period., > ^ > A comma is missing there. Also, there's a redundant comma at the end. > And I would rephrase: > If set to `short', only show the first sentence of the doc string. Done. --==-=-= Content-Type: text/html; charset=utf-8 Content-Transfer-Encoding: quoted-printable

Eli Zaretskii <eliz@gnu.org> writes:

From: Elijah Gabe P=C3=A9rez <eg642616@gmail.com>
Cc: 77124@debbugs.gnu.org
Date: Thu, 20 Mar 2025 12:37:23 -0600

— a/etc/NEWS
+ b/etc/NEWS
@@ -1900,6 +1900,17 @@ another pattern matching syntax that is different fr= om that of 'pcase',
which some users might find less cryptic.
See the Info node "(elisp) cond* Macro" for details.

+—
+** New eldoc function 'elisp-eldoc-funcall-with-docstring'.
+This function includes the current function docstring in eldoc echo area +and can be used as a more detailed alternative to 'elisp-eldoc-funcall'. +
+** New user option 'elisp-eldoc-funcall-with-docstring-lenght'.
+This user option specifies how long function docstring must be displayed +in 'elisp-eldoc-funcall-with-docstring'. If set to 'short' only display +cut docstring before period. Otherwise if set to 'full', display full
+docstring.'

These two entries should be moved to a separate section "ElDoc" under<= br /> "Changes in Specialized Modes and Packages in Emacs 31.1".

Also, please mark the second entry with "—", and fix a typo the= re
("length").

+(defcustom elisp-eldoc-funcall-with-docstring-lenght 'short
+ "Specify function docstring lenght in `elisp-eldoc-funcall-with-docstrin= g'.

"Control length of doc string shown by `elisp-eldoc-funcall-with-docst= ring'."

(Note the typo: "length".)

+If set to `short' only display docstring before period.,
^
A comma is missing there. Also, there's a redundant comma at the end.
And I would rephrase:

If set to `short', only show the first sentence of the doc string.

Done.

--==-=-=-- --=-=-= Content-Type: text/x-patch Content-Disposition: attachment; filename=0001-Optionally-display-function-docstring-in-eldoc.patch >From 2644e590277c6d3f38b2bc3b3da42526ee256475 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?El=C3=ADas=20Gabriel=20P=C3=A9rez?= Date: Wed, 19 Mar 2025 12:01:22 -0600 Subject: [PATCH] Optionally display function docstring in eldoc Allow display (optionally) function docstring in eldoc. (Bug#77124) * etc/NEWS: Document changes. * lisp/progmodes/elisp-mode.el (elisp-eldoc-funcall-with-docstring-length): New user option. (elisp-eldoc-funcall-with-docstring): New function. --- etc/NEWS | 13 +++++++++++ lisp/progmodes/elisp-mode.el | 44 ++++++++++++++++++++++++++++++++++++ 2 files changed, 57 insertions(+) diff --git a/etc/NEWS b/etc/NEWS index cc63d03eafe..16934dfb21b 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -534,6 +534,19 @@ The prompts 'opstring' and 'active-opstring' can now either be strings or functions. This is useful when your prompts can benefit from dynamic content. +** ElDoc +--- +*** New eldoc function 'elisp-eldoc-funcall-with-docstring'. +This function includes the current function docstring in eldoc echo area +and can be used as a more detailed alternative to 'elisp-eldoc-funcall'. + +--- +*** New user option 'elisp-eldoc-funcall-with-docstring-length'. +This user option specifies how long function docstring must be displayed +in 'elisp-eldoc-funcall-with-docstring'. If set to 'short' only display +cut docstring before period. Otherwise if set to 'full', display full +docstring.' + --- ** Buffer Menu diff --git a/lisp/progmodes/elisp-mode.el b/lisp/progmodes/elisp-mode.el index a34f29bffea..748d2f11360 100644 --- a/lisp/progmodes/elisp-mode.el +++ b/lisp/progmodes/elisp-mode.el @@ -1845,6 +1845,50 @@ elisp-eldoc-funcall 'font-lock-function-name-face 'font-lock-keyword-face))))) +(defcustom elisp-eldoc-funcall-with-docstring-length 'short + "Control length of doc string shown by `elisp-eldoc-funcall-with-docstring'. +If set to `short', only show the first sentence of the doc string. +Otherwise if set to `full', display full doc string." + :type '(choice + (const :tag "Short" short) + (const :tag "Full" full)) + :group 'elisp + :version "31.1") + +(defun elisp-eldoc-funcall-with-docstring (callback &rest _ignored) + "Document function call at point by calling CALLBACK. +Intended for `eldoc-documentation-functions' (which see). +Compared to `elisp-eldoc-funcall', this also includes the +current function doc string, doc string length depends on +`elisp-eldoc-funcall-with-docstring-length'." + (let* ((sym-info (elisp--fnsym-in-current-sexp)) + (fn-sym (car sym-info)) + (doc (when (fboundp fn-sym) + (propertize + (cdr (help-split-fundoc + (condition-case nil (documentation fn-sym t) + (invalid-function nil)) + fn-sym)) + 'face 'font-lock-doc-face)))) + (when fn-sym + (funcall callback + (concat (apply #'elisp-get-fnsym-args-string sym-info) + ;; Ensure not display the docstring in the + ;; mode-line. + (when (and doc (not (minibufferp))) + (concat + "\n" + (pcase elisp-eldoc-funcall-with-docstring-length + ('full doc) + ('short + (save-match-data + (when (string-match "\\." doc) + (concat "\n" (substring doc 0 (match-end 0)))))))))) + :thing fn-sym + :face (if (functionp fn-sym) + 'font-lock-function-name-face + 'font-lock-keyword-face))))) + (defun elisp-eldoc-var-docstring (callback &rest _ignored) "Document variable at point by calling CALLBACK. Intended for `eldoc-documentation-functions' (which see). -- 2.49.0 --=-=-= Content-Type: text/plain -- - E.G via GNU Emacs and Org. --=-=-=-- From debbugs-submit-bounces@debbugs.gnu.org Sat Apr 05 05:18:24 2025 Received: (at 77124-done) by debbugs.gnu.org; 5 Apr 2025 09:18:24 +0000 Received: from localhost ([127.0.0.1]:41531 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1u0zfT-0006yw-S4 for submit@debbugs.gnu.org; Sat, 05 Apr 2025 05:18:24 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:52442) by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.84_2) (envelope-from ) id 1u0zfP-0006yd-Td for 77124-done@debbugs.gnu.org; Sat, 05 Apr 2025 05:18:20 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1u0zfI-0008Jt-C0; Sat, 05 Apr 2025 05:18:13 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-version:References:Subject:In-Reply-To:To:From: Date; bh=OVW4PSAK1/PD4/+cjKbZTl5DqrCgXhV0OcB7Lvtuq54=; b=DYU5I44qE7m7iFcDZj0D g/VoaU1s42ci+GYt11kMDLqV/8i1ItVm+yKjR8GFatIc/0mnkgrA4+ZSMmNWhRd0bjhJvWo4x7/9X SOHuropqtaMdVjKiiHRyzPZGQnBdq/jbfokCjCxWUJJMRDY1z1TblZDjhZudxhLIgFl1NnpNnmhAv BlMGYRMTlsxZV3CfjOIqUEEJDlcC38fsQipIeyFP7jtwaeBXciC2PZc2YHrG0HjBKy43nh7ALBw1v 54leTdjlyQSTJAlXYNV4TgdRJkwspI9NF5kQJ5IvmbwExswnw392gPJw7FvlTwQ/6DRBoEpzVD1C4 ABscvtwUeCJZjQ==; Date: Sat, 05 Apr 2025 12:18:07 +0300 Message-Id: <86wmbzvueo.fsf@gnu.org> From: Eli Zaretskii To: Elijah Gabe =?utf-8?Q?P=C3=A9rez?= In-Reply-To: <87jz87pr49.fsf@gmail.com> (message from Elijah Gabe =?utf-8?Q?P=C3=A9rez?= on Sat, 29 Mar 2025 13:35:18 -0600) Subject: Re: bug#77124: [PATCH] Optionally display function docstring in eldoc References: <871pus50sw.fsf@gmail.com> <86zfhfnb1y.fsf@gnu.org> <87sen7h7ks.fsf@gmail.com> <86msd46oy0.fsf@gnu.org> <87jz87pr49.fsf@gmail.com> MIME-version: 1.0 Content-type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 77124-done Cc: 77124-done@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Elijah Gabe Pérez > Cc: 77124@debbugs.gnu.org > Date: Sat, 29 Mar 2025 13:35:18 -0600 > > Eli Zaretskii writes: > > From: Elijah Gabe Pérez > Cc: 77124@debbugs.gnu.org > Date: Thu, 20 Mar 2025 12:37:23 -0600 > > — a/etc/NEWS > + b/etc/NEWS > @@ -1900,6 +1900,17 @@ another pattern matching syntax that is different from that of 'pcase', > which some users might find less cryptic. > See the Info node "(elisp) cond* Macro" for details. > > +— > +** New eldoc function 'elisp-eldoc-funcall-with-docstring'. > +This function includes the current function docstring in eldoc echo area > +and can be used as a more detailed alternative to 'elisp-eldoc-funcall'. > + > +** New user option 'elisp-eldoc-funcall-with-docstring-lenght'. > +This user option specifies how long function docstring must be displayed > +in 'elisp-eldoc-funcall-with-docstring'. If set to 'short' only display > +cut docstring before period. Otherwise if set to 'full', display full > +docstring.' > > These two entries should be moved to a separate section "ElDoc" under > "Changes in Specialized Modes and Packages in Emacs 31.1". > > Also, please mark the second entry with "—", and fix a typo there > ("length"). > > +(defcustom elisp-eldoc-funcall-with-docstring-lenght 'short > + "Specify function docstring lenght in `elisp-eldoc-funcall-with-docstring'. > > "Control length of doc string shown by `elisp-eldoc-funcall-with-docstring'." > > (Note the typo: "length".) > > +If set to `short' only display docstring before period., > > ^ > A comma is missing there. Also, there's a redundant comma at the end. > And I would rephrase: > > If set to `short', only show the first sentence of the doc string. > > Done. Thanks, installed on the master branch, and closing the bug. From unknown Wed Jul 16 00:58:11 2025 Received: (at fakecontrol) by fakecontrolmessage; To: internal_control@debbugs.gnu.org From: Debbugs Internal Request Subject: Internal Control Message-Id: bug archived. Date: Sat, 03 May 2025 11:24:10 +0000 User-Agent: Fakemail v42.6.9 # This is a fake control message. # # The action: # bug archived. thanks # This fakemail brought to you by your local debbugs # administrator