From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.ciao.gmane.io!not-for-mail From: Madhu Newsgroups: gmane.emacs.devel Subject: Re: Poor quality documentation in edebug.el, and recursive documentation. Date: Tue, 12 May 2020 12:03:49 +0530 Message-ID: References: <20200505202048.GA15482@ACM> <20200508195326.GB6705@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="95891"; mail-complaints-to="usenet@ciao.gmane.io" To: emacs-devel@gnu.org Cancel-Lock: sha1:nummK+0kTGJ/58ZMKaOF0mTzMHE= Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Tue May 12 08:34:40 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 1jYOUy-000Oq6-MQ for ged-emacs-devel@m.gmane-mx.org; Tue, 12 May 2020 08:34:40 +0200 Original-Received: from localhost ([::1]:32808 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jYOUx-0006oN-MT for ged-emacs-devel@m.gmane-mx.org; Tue, 12 May 2020 02:34:39 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:50212) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jYOUP-00066O-7K for emacs-devel@gnu.org; Tue, 12 May 2020 02:34:05 -0400 Original-Received: from ciao.gmane.io ([159.69.161.202]:56608) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jYOUO-0006fn-5q for emacs-devel@gnu.org; Tue, 12 May 2020 02:34:04 -0400 Original-Received: from list by ciao.gmane.io with local (Exim 4.92) (envelope-from ) id 1jYOUM-000OAi-JY for emacs-devel@gnu.org; Tue, 12 May 2020 08:34:02 +0200 X-Injected-Via-Gmane: http://gmane.org/ Received-SPF: pass client-ip=159.69.161.202; envelope-from=ged-emacs-devel@m.gmane-mx.org; helo=ciao.gmane.io X-detected-operating-system: by eggs.gnu.org: First seen = 2020/05/12 02:34:02 X-ACL-Warn: Detected OS = Linux 3.11 and newer [fuzzy] X-Spam_score_int: -16 X-Spam_score: -1.7 X-Spam_bar: - X-Spam_report: (-1.7 / 5.0 requ) BAYES_00=-1.9, HEADER_FROM_DIFFERENT_DOMAINS=0.249, 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:249941 Archived-At: * Stefan Monnier : Wrote on Fri, 08 May 2020 16:24:28 -0400: >> where I was at the beginning of the week. I don't know what a >> "metaclass" is, > > It's a generic term from the OO crowd. It's class of a class: in > languages where classes can be manipulated as normal objects, they > themselves belong to a class, called the metaclass (which is hence > itself a class with its own metaclass, etc...). > > Luckily you shouldn't need to know any of those things unless you need > to dig into the implementation of Elisp's OO facilities such as > `cl-defstruct`, `eieio`, or `cl-generic`, basically. Unfortunately we need to know because we have to deal with your misdesign of those features and language constructs. While the concepts are ostensibky taken from common lisp the implementation shares none of the spirit of lisp which makes it impossible to work with. Redefinitions of cl-generics are not possible. I have repeatedly come across code that uses these features you have introduced, which get into debug situations where emacs cannot be debugged but needs be killed. I have cases (related debbug) when edbug is essentially unusable and worse it is so *by your design*. These are not problems that are fixable without fixing your implementation. > >> I'm still not sure what a cl-structure-class is and the >> latter needs documenting coherently. > > I guess it would be good, yes. In the mean time, just like for a lot of > the CL stuff you can start by looking it up in the HyperSpec: > http://www.lispworks.com/documentation/HyperSpec/Body/t_stu_cl.htm#structure-class Again these do not help deal with your perverse idiosyncratic "write only" implementations which implement your particular nauseous flavour and opinion of the language which is now forced on elisp. There isnt any way to submit patches to your code. The elisp code base has been irrecoverably subverted by your contributions and there is no way to go back to the pleasurable debugging-eden which emacs was before you started "contributing" > >>> > "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). >> >> It most assuredly does not. It _lists_ those fields - it does not >> describe them. One of these fields, for example, is called named. What >> does named do? What does it represent? What's it for? None of these >> questions is answered. named is undocumented, as are all the other >> fields. Why? > > Why do you need to know? In order to deal with mishbehaving code which uses the features and code which you have authored. It is no longer the case that understanding the principles of lisp is enough to deal with emacs lisp. Every particular twist in thinking that you have painfully gone through and opaquely introduced into the code base has to be unravelled and worked around before a piece of code can be understood and debugged. > This class is used by `cl-defstruct` and pretty much nothing else, so > presumably if you need to know about it you're hacking on > `cl-defstruct`, and if you're hacking on `cl-defstruct` the first thing > to do is to look up its documentation (unless you know it already, > obviously). After that it should be trivial to guess what this `named` > field is used for. > > In your case, you're investigating `edebug--frame`, which should not > depend on the way `cl-defstruct` is implemented. Kind of like looking > at the "vtables" generated by your C++ compiler. Like vtables the intent again is code obfuscation - and the lead up to the its "open source you have the code" taunt >> A better way would be actually to document it. > > Be my guest. Another taunt - which seems to be the basic motivation for your "contributions" to emacs.