From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.ciao.gmane.io!not-for-mail From: Stefan Monnier Newsgroups: gmane.emacs.devel Subject: Re: Poor quality documentation in edebug.el, and recursive documentation. Date: Tue, 05 May 2020 18:18:26 -0400 Message-ID: References: <20200505202048.GA15482@ACM> Mime-Version: 1.0 Content-Type: text/plain Injection-Info: ciao.gmane.io; posting-host="ciao.gmane.io:159.69.161.202"; logging-data="121983"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux) Cc: emacs-devel@gnu.org To: Alan Mackenzie Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Wed May 06 00:19:03 2020 Return-path: Envelope-to: ged-emacs-devel@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 1jW5u2-000Vf1-Dy for ged-emacs-devel@m.gmane-mx.org; Wed, 06 May 2020 00:19:02 +0200 Original-Received: from localhost ([::1]:51298 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jW5u1-0006l7-FO for ged-emacs-devel@m.gmane-mx.org; Tue, 05 May 2020 18:19:01 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:38734) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jW5tZ-0006Le-0x for emacs-devel@gnu.org; Tue, 05 May 2020 18:18:33 -0400 Original-Received: from mailscanner.iro.umontreal.ca ([132.204.25.50]:12860) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jW5tX-0008WV-3G for emacs-devel@gnu.org; Tue, 05 May 2020 18:18:31 -0400 Original-Received: from pmg1.iro.umontreal.ca (localhost.localdomain [127.0.0.1]) by pmg1.iro.umontreal.ca (Proxmox) with ESMTP id C792A101250; Tue, 5 May 2020 18:18:29 -0400 (EDT) Original-Received: from mail01.iro.umontreal.ca (unknown [172.31.2.1]) by pmg1.iro.umontreal.ca (Proxmox) with ESMTP id EED70101174; Tue, 5 May 2020 18:18:27 -0400 (EDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=iro.umontreal.ca; s=mail; t=1588717107; bh=xZ3ylfCmCp9qcdZaMwZNZiXW0uX+SkWtjmKi4ViMLDg=; h=From:To:Cc:Subject:References:Date:In-Reply-To:From; b=nsN2cL1tRWoda4GQuxiA7LiPgstxIpnUqz5AL2b9fBY+STFfsVbgqBLEudS74wYvg Uykmqhk2y0RFxxM4Fgv0ybNwC1ZAVgu52p85+CIB+Tl3XvxNGb1F1U2ZOZXFjA52MQ PLQpRQpNOxJN3Ih9Q3qzcaPx6uT8FAxXx2MlW1b+1hUzB2aZVPUK+R937RpVc0Bf9C nB8iPPkmG1wZBm+mt0iPBiwu11inV5RBOo4CywKnD6eIR4LaXx31xdbGxfgSo8tC3v 4sLHCdLmYt46mpdXcM2mMqgk6qlMAmWKSMtf91YXHPFLyDXJhO1g7dAc0llYqZJX3d 2C9N+N5Nv3KbQ== Original-Received: from alfajor (unknown [216.154.3.202]) by mail01.iro.umontreal.ca (Postfix) with ESMTPSA id 89DA8120484; Tue, 5 May 2020 18:18:27 -0400 (EDT) In-Reply-To: <20200505202048.GA15482@ACM> (Alan Mackenzie's message of "Tue, 5 May 2020 20:20:48 +0000") Received-SPF: pass client-ip=132.204.25.50; envelope-from=monnier@iro.umontreal.ca; helo=mailscanner.iro.umontreal.ca X-detected-operating-system: by eggs.gnu.org: First seen = 2020/05/05 13:23:34 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] X-Spam_score_int: -42 X-Spam_score: -4.3 X-Spam_bar: ---- X-Spam_report: (-4.3 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, RCVD_IN_DNSWL_MED=-2.3, SPF_PASS=-0.001, URIBL_BLOCKED=0.001 autolearn=_AUTOLEARN X-Spam_action: no action X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.io gmane.emacs.devel:249056 Archived-At: > Access slot "def-name" of `edebug--frame' struct CL-X. > > Huh? Do I really care about whether it has a compiler macro? I > certainly care about what this function does, and the one liner is > gibberish. Not sure what you mean by gibberish. The function itself is a one-liner, all it does is (as the docstring says) is that it accesses the slot called "def-name" of the struct CL-X which is presumed to be of type `edebug--frame`. > What significance does it have in edebug? The "--" indicates it's an internal function. These are quit often not documented. > What is the return value of this > function? All of these points are left open by this alleged doc string. > What does CL-X mean? It's the name of the argument, as always. See the earlier line: (edebug--frame-def-name CL-X) The choice of `CL-X` as argument name is indeed poor. It should probably be ARG or V or X instead. The use of a `cl-` prefix is a remnant of the time where we didn't have lexical scoping, IIRC. > It carries on. If you put point over the `edebug.el' and type , it > doesn't go to the defining function, throwing an error instead. Indeed, that's unfortunate. We should improve either `cl-defstruct` or `find-function` to fix this. > It caries on further, and if anything, gets steadily worse: put point > over `edebug-frame' and hit . It leads to another vacuous doc > string. This one can be improved by the patch below (which is the kind of patch you reject in CC-mode, ironically enough). > ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; > So, what is a cl-structure-class? You said so yourself: Since `edebug--frame` is a type of type `cl-structure-class`, then `cl-structure-class` is a "type of types". IOW a metaclass. > "cl-structure-class is a type (of kind `cl-structure-class')" > > embedded in approximately 26 lines, none of which shed any light on what > a cl-structure-class is, does, or represents. There actual docstring says: "The type of CL structs descriptors." The rest describes the fields of those CL struct descriptors (aka class objects). Since we're in the realm of metaclasses here, it's no wonder that the info you'll find here won't be very helpful to understand `edebug--frame-def-name`. > Following the link just redisplays the current doc string, > ad infinitum. Indeed, this metaclass is its own metaclass (that's the usual way to stop the recursion). Stefan diff --git a/lisp/emacs-lisp/edebug.el b/lisp/emacs-lisp/edebug.el index a376067443a..1b4bbb54e59 100644 --- a/lisp/emacs-lisp/edebug.el +++ b/lisp/emacs-lisp/edebug.el @@ -4169,12 +4169,12 @@ edebug-instrumented-backtrace-frames "Stack frames of the current Edebug Backtrace buffer with instrumentation. This should be a list of `edebug---frame' objects.") -;; Data structure for backtrace frames with information -;; from Edebug instrumentation found in the backtrace. (cl-defstruct (edebug--frame (:constructor edebug--make-frame) (:include backtrace-frame)) + "Data structure for backtrace frames with information +from Edebug instrumentation found in the backtrace." def-name before-index after-index) (defun edebug-pop-to-backtrace ()