From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.ciao.gmane.io!not-for-mail From: Alan Mackenzie Newsgroups: gmane.emacs.devel Subject: Poor quality documentation in edebug.el, and recursive documentation. Date: Tue, 5 May 2020 20:20:48 +0000 Message-ID: <20200505202048.GA15482@ACM> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Injection-Info: ciao.gmane.io; posting-host="ciao.gmane.io:159.69.161.202"; logging-data="128468"; mail-complaints-to="usenet@ciao.gmane.io" To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Tue May 05 22:21:51 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 1jW44c-000XKe-T6 for ged-emacs-devel@m.gmane-mx.org; Tue, 05 May 2020 22:21:50 +0200 Original-Received: from localhost ([::1]:57716 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jW44b-0007F1-UZ for ged-emacs-devel@m.gmane-mx.org; Tue, 05 May 2020 16:21:49 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:44096) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jW43i-0006YD-FK for emacs-devel@gnu.org; Tue, 05 May 2020 16:20:54 -0400 Original-Received: from colin.muc.de ([193.149.48.1]:29317 helo=mail.muc.de) by eggs.gnu.org with smtp (Exim 4.90_1) (envelope-from ) id 1jW43g-0005Yl-Rk for emacs-devel@gnu.org; Tue, 05 May 2020 16:20:54 -0400 Original-Received: (qmail 51640 invoked by uid 3782); 5 May 2020 20:20:48 -0000 Original-Received: from acm.muc.de (p4FE15C35.dip0.t-ipconnect.de [79.225.92.53]) by localhost.muc.de (tmda-ofmipd) with ESMTP; Tue, 05 May 2020 22:20:48 +0200 Original-Received: (qmail 15721 invoked by uid 1000); 5 May 2020 20:20:48 -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/05/05 16:20:49 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_PASS=-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:249034 Archived-At: In the master branch in function edebug--backtrace-goto-source there is a call to function edebug--frame-def-name. The doc string of the latter is, in its entirety: edebug--frame-def-name is a compiled Lisp function in `edebug.el'. (edebug--frame-def-name CL-X) This function has a compiler macro `edebug--frame-def-name--cmacro'. This function does not change global state, including the match data. 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. "Access slot "def-name" .... struct CL-X."? Is "Access" a verb or an adjective, here? What on earth is a "def-name"? What significance does it have in edebug? 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 carries on. If you put point over the `edebug.el' and type , it doesn't go to the defining function, throwing an error instead. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; It caries on further, and if anything, gets steadily worse: put point over `edebug-frame' and hit . It leads to another vacuous doc string. An `edebug-frame' is a type. Great! It is a type of type cl-structure-class, whatever one of those is. There follows a columnar list of something, and some gobbledegook about "Specialized Methods", whatever they are. I don't understand it. At least the link to the source works for `edebug-frame'. The source contains NO documentation string, and it is not obvious what an edebug-frame is or does. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; So, what is a cl-structure-class? From the most recent doc-string, follow the link. We get to another doc string, a profoundly useless one, which reads "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. Following the link just redisplays the current doc string, ad infinitum. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; Maybe RTFMing will shed light. Nope: in cl.info, there's not a single mention of cl-structure-class. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; DOC STRINGS MATTER!!! Not, perhaps in every last minor private function in every package, but in obscure cl-* functions used widely throughout Emacs they most definitely do. Can we please stop writing code like this? For everybody but an elite who likes this sort of thing, it's a massive time sink. As this sort of code is steadily proliferated through Emacs, the amount of code readily maintainable by anybody steadily decreases. Only this elite can effectively manage stuff with cl-structure-class in it. This is not good for Emacs. I don't doubt I could, by reading the code, work out what cl-structure-class does. But it would be time consuming and dreary, I would soon forget it again, and I've got plenty of other things to do. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; So, would somebody who likes it please document cl-structure-class and its friends adequately? Would somebody please add a doc string, a good one, to `edebug-frame'? Thanks! -- Alan Mackenzie (Nuremberg, Germany).