From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Alan Mackenzie Newsgroups: gmane.emacs.bugs Subject: bug#42776: Obscure documentation of `edebug-form-data' in edebug.el Date: Sun, 9 Aug 2020 15:03:41 +0000 Message-ID: <20200809150341.GA26635@ACM> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="10927"; mail-complaints-to="usenet@ciao.gmane.io" To: 42776@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Sun Aug 09 17:04:18 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 1k4mrw-0002gK-KG for geb-bug-gnu-emacs@m.gmane-mx.org; Sun, 09 Aug 2020 17:04:16 +0200 Original-Received: from localhost ([::1]:54650 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1k4mrv-0006DS-EW for geb-bug-gnu-emacs@m.gmane-mx.org; Sun, 09 Aug 2020 11:04:15 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:53886) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1k4mrj-0006DA-6A for bug-gnu-emacs@gnu.org; Sun, 09 Aug 2020 11:04:03 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:49957) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1k4mri-00080U-SC for bug-gnu-emacs@gnu.org; Sun, 09 Aug 2020 11:04:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1k4mri-0007HO-Co for bug-gnu-emacs@gnu.org; Sun, 09 Aug 2020 11:04:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Alan Mackenzie Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 09 Aug 2020 15:04:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 42776 X-GNU-PR-Package: emacs X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Original-Received: via spool by submit@debbugs.gnu.org id=B.159698543227963 (code B ref -1); Sun, 09 Aug 2020 15:04:02 +0000 Original-Received: (at submit) by debbugs.gnu.org; 9 Aug 2020 15:03:52 +0000 Original-Received: from localhost ([127.0.0.1]:33270 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1k4mrY-0007Gu-Fb for submit@debbugs.gnu.org; Sun, 09 Aug 2020 11:03:52 -0400 Original-Received: from lists.gnu.org ([209.51.188.17]:57116) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1k4mrV-0007Gl-C1 for submit@debbugs.gnu.org; Sun, 09 Aug 2020 11:03:51 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:53884) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1k4mrV-0006As-4X for bug-gnu-emacs@gnu.org; Sun, 09 Aug 2020 11:03:49 -0400 Original-Received: from colin.muc.de ([193.149.48.1]:34390 helo=mail.muc.de) by eggs.gnu.org with smtp (Exim 4.90_1) (envelope-from ) id 1k4mrS-000808-TF for bug-gnu-emacs@gnu.org; Sun, 09 Aug 2020 11:03:48 -0400 Original-Received: (qmail 43572 invoked by uid 3782); 9 Aug 2020 15:03:42 -0000 Original-Received: from acm.muc.de (p2e5d5e8f.dip0.t-ipconnect.de [46.93.94.143]) by localhost.muc.de (tmda-ofmipd) with ESMTP; Sun, 09 Aug 2020 17:03:42 +0200 Original-Received: (qmail 26677 invoked by uid 1000); 9 Aug 2020 15:03:41 -0000 Content-Disposition: inline X-Delivery-Agent: TMDA/1.1.12 (Macallan) X-Primary-Address: acm@muc.de Received-SPF: pass client-ip=193.149.48.1; envelope-from=acm@muc.de; helo=mail.muc.de X-detected-operating-system: by eggs.gnu.org: First seen = 2020/08/09 11:03:43 X-ACL-Warn: Detected OS = FreeBSD 9.x or newer [fuzzy] X-Spam_score_int: -18 X-Spam_score: -1.9 X-Spam_bar: - X-Spam_report: (-1.9 / 5.0 requ) BAYES_00=-1.9, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action 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:184430 Archived-At: Hello, Emacs. In the master branch: The doc string of edebug-form-data begins thusly: "A list of entries associating symbols with buffer regions. Each entry is an `edebug--form-data' struct with fields: SYMBOL, BEGIN-MARKER, and END-MARKER. The markers are at the beginning and end of an entry level form and SYMBOL is a symbol that holds all edebug related information for the form on its property list." The following extract from this is obscure: "...the beginning and end of an entry level form ...." What in heaven or earth is an "entry level form"? What is it for? Less major questions are: What is the nature of the "association" of the symbols with the buffer regions? Which buffer gets its regions associated? It seems the only way to make sense of this doc string is by reading edebug.el's source to find out what it means. This isn't what doc strings are supposed to be for. This is a bug. -- Alan Mackenzie (Nuremberg, Germany).