From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#22336: 25.0.50; cl-generic.el features are not documented in ELisp manual Date: Sat, 23 Jan 2016 14:51:36 +0200 Message-ID: <83d1ss5uhz.fsf@gnu.org> References: <83h9innmtv.fsf@gnu.org> <831t9iexrw.fsf@gnu.org> <8337tp71q5.fsf@gnu.org> <56A30FCE.4030009@yandex.ru> <83twm46d8y.fsf@gnu.org> <56A337B3.9050802@yandex.ru> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org X-Trace: ger.gmane.org 1453553543 5714 80.91.229.3 (23 Jan 2016 12:52:23 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 23 Jan 2016 12:52:23 +0000 (UTC) Cc: 22336@debbugs.gnu.org To: Dmitry Gutov Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sat Jan 23 13:52:12 2016 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1aMxfn-0004qi-KR for geb-bug-gnu-emacs@m.gmane.org; Sat, 23 Jan 2016 13:52:11 +0100 Original-Received: from localhost ([::1]:57073 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aMxfm-0007Cg-G2 for geb-bug-gnu-emacs@m.gmane.org; Sat, 23 Jan 2016 07:52:10 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:53666) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aMxfi-0007CY-46 for bug-gnu-emacs@gnu.org; Sat, 23 Jan 2016 07:52:07 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aMxfe-000724-Sr for bug-gnu-emacs@gnu.org; Sat, 23 Jan 2016 07:52:06 -0500 Original-Received: from debbugs.gnu.org ([208.118.235.43]:41910) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aMxfe-000720-Pw for bug-gnu-emacs@gnu.org; Sat, 23 Jan 2016 07:52:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84) (envelope-from ) id 1aMxfe-0001ke-II for bug-gnu-emacs@gnu.org; Sat, 23 Jan 2016 07:52:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 23 Jan 2016 12:52:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 22336 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 22336-submit@debbugs.gnu.org id=B22336.14535534886676 (code B ref 22336); Sat, 23 Jan 2016 12:52:02 +0000 Original-Received: (at 22336) by debbugs.gnu.org; 23 Jan 2016 12:51:28 +0000 Original-Received: from localhost ([127.0.0.1]:58363 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84) (envelope-from ) id 1aMxf5-0001jc-TE for submit@debbugs.gnu.org; Sat, 23 Jan 2016 07:51:28 -0500 Original-Received: from eggs.gnu.org ([208.118.235.92]:34377) by debbugs.gnu.org with esmtp (Exim 4.84) (envelope-from ) id 1aMxf4-0001jI-F2 for 22336@debbugs.gnu.org; Sat, 23 Jan 2016 07:51:27 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aMxew-0006l7-58 for 22336@debbugs.gnu.org; Sat, 23 Jan 2016 07:51:21 -0500 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:47895) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aMxew-0006l3-1R; Sat, 23 Jan 2016 07:51:18 -0500 Original-Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:2184 helo=HOME-C4E4A596F7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_128_CBC_SHA1:128) (Exim 4.82) (envelope-from ) id 1aMxev-00010e-CO; Sat, 23 Jan 2016 07:51:17 -0500 In-reply-to: <56A337B3.9050802@yandex.ru> (message from Dmitry Gutov on Sat, 23 Jan 2016 11:20:03 +0300) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.43 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.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:111885 Archived-At: > Cc: 22336@debbugs.gnu.org > From: Dmitry Gutov > Date: Sat, 23 Jan 2016 11:20:03 +0300 > > On 01/23/2016 09:06 AM, Eli Zaretskii wrote: > > > Note that the doc strings don't tell everything I wrote, and sometimes > > seem to say inaccurate or even contradictory things, so if what I > > wrote correctly describes what the implementation actually does, the > > doc strings (as well as some of the comments) in cl-generic.el should > > probably be brought in line with the reality. > > Could you give an example of them being wrong? (defmacro cl-defgeneric (name args &rest options-and-methods) "Create a generic function NAME. DOC-STRING is the base documentation for this class. A generic function has no body, as its purpose is to decide which method body is appropriate to use. Specific methods are defined with `cl-defmethod'. With this implementation the ARGS are currently ignored. OPTIONS-AND-METHODS currently understands: - (:documentation DOCSTRING) - (declare DECLARATIONS) - (:argument-precedence-order &rest ARGS) - (:method [QUALIFIERS...] ARGS &rest BODY) BODY, if present, is used as the body of a default method. \(fn NAME ARGS [DOC-STRING] [OPTIONS-AND-METHODS...] &rest BODY)" It says a generic function has no body, but the usage info does mention body, and the last part of the doc string says BODY if present is used as the default method. Or is that the body of :method? Anyway, specific methods can evidently be defined by cl-defgeneric as well, whereas the doc string says they should be defined by cl-defmethod. The semantics of :method is never described at all (and I saw no examples of its usage to inspire me, AFAIR). (defmacro cl-defmethod (name args &rest body) "Define a new method for generic function NAME. I.e. it defines the implementation of NAME to use for invocations where the value of the dispatch argument matches the specified TYPE. The dispatch argument has to be one of the mandatory arguments, and all methods of NAME have to use the same argument for dispatch. The dispatch argument and TYPE are specified in ARGS where the corresponding formal argument appears as (VAR TYPE) rather than just VAR. The optional second argument QUALIFIER is a specifier that modifies how the method is combined with other methods, including: :before - Method will be called before the primary :after - Method will be called after the primary :around - Method will be called around everything else The absence of QUALIFIER means this is a \"primary\" method. Other than a type, TYPE can also be of the form `(eql VAL)' in which case this method will be invoked when the argument is `eql' to VAL. \(fn NAME [QUALIFIER] ARGS &rest [DOCSTRING] BODY)" "_The_ dispatch argument", in singular means only one such argument is possible, which is of course false. The &context dispatch has a slightly different syntax, but it isn't mentioned here at all, which makes the description of (VAR TYPE) incorrect in that case. > I only things omitted in > docstrings (but which can be inferred from the commentary, such as > dispatch on types such as integer, string, and so on). Some omissions are very hard to restore. The most striking example is TYPE, about which the doc string says nothing at all, and the commentary says just "plain old types". How could you arrive at the long list that's now in the manual, let alone the type hierarchy that goes with it, except by reading the sources? As another example, the ":extra STRING" feature is mentioned, but without any details; I couldn't understand how to use it in practice (it is not used in the tests, either). And I don't recommend believing the commentary too much, either. E.g., what it says about &context in several places is contradictory: ;; E.g. (foo &context (major-mode (eql c-mode))) is an arglist specifying ;; that this method will only be applicable when `major-mode' has value ;; `c-mode'. and then: ;; - then define a context-rewriter so you can write ;; "&context (major-mode c-mode)" rather than ;; "&context (major-mode (derived-mode c-mode))". and even ;; TODO: ;; ;; - A way to dispatch on the context (e.g. the major-mode, some global ;; variable, you name it). which makes you think it isn't even implemented... Also, there's something about derived-mode there, but it's so contrived and devoid of examples, that I didn't even put that in the manual. There were others I was only too happy to forget. I needed to read the CLOS documentation to make sense of some things. Of course, cl-generic.el doesn't implement all of CLOS, and then adds extension that are not in CLOS, so even CLOS documentation only helps up to a point.