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 19:21:26 +0200 Message-ID: <83pows43ft.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> <83d1ss5uhz.fsf@gnu.org> <56A3B22C.80902@yandex.ru> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org X-Trace: ger.gmane.org 1453569749 22999 80.91.229.3 (23 Jan 2016 17:22:29 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 23 Jan 2016 17:22:29 +0000 (UTC) Cc: 22336@debbugs.gnu.org, monnier@IRO.UMontreal.CA To: Dmitry Gutov Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sat Jan 23 18:22:15 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 1aN1t7-0000PO-MA for geb-bug-gnu-emacs@m.gmane.org; Sat, 23 Jan 2016 18:22:13 +0100 Original-Received: from localhost ([::1]:58109 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aN1t3-0008V0-Q8 for geb-bug-gnu-emacs@m.gmane.org; Sat, 23 Jan 2016 12:22:09 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:44984) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aN1sz-0008Un-6d for bug-gnu-emacs@gnu.org; Sat, 23 Jan 2016 12:22:06 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aN1sv-0004Wj-Vc for bug-gnu-emacs@gnu.org; Sat, 23 Jan 2016 12:22:05 -0500 Original-Received: from debbugs.gnu.org ([208.118.235.43]:44319) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aN1sv-0004WX-S6 for bug-gnu-emacs@gnu.org; Sat, 23 Jan 2016 12:22:01 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84) (envelope-from ) id 1aN1sv-0001yy-OL for bug-gnu-emacs@gnu.org; Sat, 23 Jan 2016 12:22:01 -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 17:22:01 +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.14535696797533 (code B ref 22336); Sat, 23 Jan 2016 17:22:01 +0000 Original-Received: (at 22336) by debbugs.gnu.org; 23 Jan 2016 17:21:19 +0000 Original-Received: from localhost ([127.0.0.1]:60772 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84) (envelope-from ) id 1aN1sF-0001xR-Fg for submit@debbugs.gnu.org; Sat, 23 Jan 2016 12:21:19 -0500 Original-Received: from eggs.gnu.org ([208.118.235.92]:53925) by debbugs.gnu.org with esmtp (Exim 4.84) (envelope-from ) id 1aN1sE-0001xC-9w for 22336@debbugs.gnu.org; Sat, 23 Jan 2016 12:21:18 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aN1s8-0004Mi-3v for 22336@debbugs.gnu.org; Sat, 23 Jan 2016 12:21:13 -0500 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:53573) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aN1s3-0004MK-Sv; Sat, 23 Jan 2016 12:21:07 -0500 Original-Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:2423 helo=HOME-C4E4A596F7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_128_CBC_SHA1:128) (Exim 4.82) (envelope-from ) id 1aN1s3-0003e1-3P; Sat, 23 Jan 2016 12:21:07 -0500 In-reply-to: <56A3B22C.80902@yandex.ru> (message from Dmitry Gutov on Sat, 23 Jan 2016 20:02:36 +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:111894 Archived-At: > Cc: 22336@debbugs.gnu.org, Stefan Monnier > From: Dmitry Gutov > Date: Sat, 23 Jan 2016 20:02:36 +0300 > > On 01/23/2016 03:51 PM, Eli Zaretskii wrote: > > > (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? > > BODY is "&rest BODY" from the advertised arglist you can see using `M-x > describe-function'. It's also visible above in the last line of the > docstring. I know. The point is the stuff contradicts itself, and when I was reading this, I needed to decide which part to believe and which to discard. I think I mostly succeeded, albeit at a significant cost; I've mentioned these only because you asked about them. > > 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). > > Is the can/should distinction a problem? Of course it is. "Should" is sometimes a synonym of "must". > I think the semantics are easy to guess, but I probably glanced at CL's > documentation as well at some point: I did guess, see what I wrote in the manual. But I shouldn't have needed to guess, I think. > > "_The_ dispatch argument", in singular means only one such argument is > > possible, which is of course false. > > Indeed. There's a case to be made for discouraging multiple-argument > dispatch ("implemented rather naively"), but the docstring should be > corrected anyway. I thought this was one of the strong points of Lisp-style OOP. > > 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? > > No idea. I was only vaguely aware, if that, of being able to dispatch on > atomic types, before reading the manual. Thanks for that. > > But the docstrings don't mention any of the possible values of TYPE > (except (eql ...)), not just "plain old" ones. So I'm not clear on what > exactly you consider an omission here. The omission is that nothing is said about what kind of objects can be used as TYPE. The idea is clear, but when you want to write code, you can only understand some of that by looking at the examples, in particular in cl-generic-tests.el (which is actually the _only_ place where you can see some -- but unfortunately not all -- of the features in action). > cl-defmethod docstring should probably enumerate the possible types > (aside from the mentioned ones, TYPE can be (head ...) or a name of > cl-struct, like the commentary says). I think so, yes. Also, it should at least hint on the hierarchy of types. > I think fixing just the things you've mentioned will already be a > step forward. Yes, of course.