From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: David Engster Newsgroups: gmane.emacs.devel Subject: Re: Better help support for EIEIO classes and methods Date: Mon, 04 Feb 2013 19:47:55 +0100 Message-ID: <87txprhq5g.fsf@engster.org> References: <877gmpz9mt.fsf@engster.org> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: ger.gmane.org 1360003684 24497 80.91.229.3 (4 Feb 2013 18:48:04 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Mon, 4 Feb 2013 18:48:04 +0000 (UTC) Cc: emacs-devel@gnu.org To: Stefan Monnier Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Feb 04 19:48:25 2013 Return-path: Envelope-to: ged-emacs-devel@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 1U2R5c-0001OW-C5 for ged-emacs-devel@m.gmane.org; Mon, 04 Feb 2013 19:48:24 +0100 Original-Received: from localhost ([::1]:41706 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1U2R5J-0006Xj-HH for ged-emacs-devel@m.gmane.org; Mon, 04 Feb 2013 13:48:05 -0500 Original-Received: from eggs.gnu.org ([208.118.235.92]:57563) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1U2R5G-0006WW-Nf for emacs-devel@gnu.org; Mon, 04 Feb 2013 13:48:03 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1U2R5F-0000VT-Dd for emacs-devel@gnu.org; Mon, 04 Feb 2013 13:48:02 -0500 Original-Received: from randomsample.de ([83.169.19.17]:55882) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1U2R5E-0000VK-Vo for emacs-devel@gnu.org; Mon, 04 Feb 2013 13:48:01 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=randomsample.de; s=a; h=Content-Type:MIME-Version:Message-ID:Date:References:In-Reply-To:Subject:Cc:To:From; bh=Y2PAQUf9gShdl7vjnNBxTAD2CIKj3ifeY67Z7b61dLM=; b=OIs3RcnGXJeTv9BYg0Ek/lgtONWp63N8GDPGTcdG/NEGgMRbbl4oCnEG8KvQGUm3D5o1KNEV0MdDLlJlnv734yH2tyA6psz2bXDQNCWBEXB2+mOypYhG25PCaLu0HBDs; Original-Received: from dslc-082-082-166-017.pools.arcor-ip.net ([82.82.166.17] helo=spaten) by randomsample.de with esmtpsa (TLS1.0:DHE_RSA_AES_128_CBC_SHA1:16) (Exim 4.72) (envelope-from ) id 1U2R5C-0004as-Fa; Mon, 04 Feb 2013 19:47:58 +0100 In-Reply-To: (Stefan Monnier's message of "Sun, 03 Feb 2013 22:28:41 -0500") User-Agent: Gnus/5.130006 (Ma Gnus v0.6) Emacs/24.2.92 (gnu/linux) Mail-Followup-To: Stefan Monnier , emacs-devel@gnu.org X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-Received-From: 83.169.19.17 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.14 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.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:156821 Archived-At: Stefan Monnier writes: >> In Emacs proper, if you use describe-function on an EIEIO class >> constructor like `auth-source-backend', you will get >> auth-source-backend is a Lisp function. as the first line, which is > >> not very helpful. If you know that this is actually a class >> constructor, you can at least call eieio-describe-class or >> eieio-describe-constructor, which will give you a much more detailed >> description, but is still missing one essential feature: a link to the >> filename where this class is defined, which quickly brings you to the >> correct class definition. This is even more important for methods, >> which can have several implementations depending on the class they're >> called on. > > To a large extent the first line is not that important since you can add > the missing info in the docstring itself. Could you give more details of > the things that can't be overcome this way? An example: Start up with emacs -Q and eval (require 'semantic/db) (require 'semantic/db-global) Then do a describe-function on semanticdb-file-table. You'll get this: ,---- | semanticdb-file-table is a Lisp function in `db.el'. | | (semanticdb-file-table &rest LOCAL-ARGS) | | From OBJ, return FILENAME's associated table object. `---- Now, this is pretty misleading since there are actually two implementations of this function, which will become clear if you use eieio-describe-generic, which will give you this: ,---- | semanticdb-file-table is a generic function with only primary methods. | | Documentation: | From OBJ, return FILENAME's associated table object. | | Implementations: | | `semanticdb-project-database' :PRIMARY (obj filename) | From OBJ, return FILENAME's associated table object. | | Defined in `db.el' | | | `semanticdb-project-database-global' :PRIMARY (obj filename) | From OBJ, return FILENAME's associated table object. | | Defined in `db-global.el' `---- This is already pretty good, but is still lacking an IMO crucial feature: the filenames 'db.el' and 'db-global.el' are not links. However, just do (add-hook 'temp-buffer-show-hook 'eieio-help-mode-augmentation-maybee t) and call eieio-describe-generic again, and you'll get links which will bring you to the correct implementations. So there are two problems here: 1) I think it should not be necessary for the user to explicitly call eieio-describe-generic; the normal describe-function should already show this information. As I've written, in CEDET upstream we do this through a defadvice. 2) How can eieio-help-mode-augmentation-maybee integrated into the current setup? And on a more general note: is the current implementation maybe considered too hack'ish? Instead of using symbol properties for storing the method's locations, should this rather be supported through load-history? -David