From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: use and doc of function symbol properties [was: bug#11381: 23.3; isearch-search-and-update issue?] Date: Mon, 28 May 2012 20:53:16 +0300 Message-ID: <83ehq419bn.fsf@gnu.org> References: <4F9DC154.2000605@groveronline.com> <87ipgggtmw.fsf@mail.jurta.org> <878vhcc4nl.fsf@mail.jurta.org> <87vcjxdt5p.fsf@mail.jurta.org> <87vcjvwtxa.fsf@mail.jurta.org> <87r4ufhfmi.fsf@mail.jurta.org> <878vge3ri7.fsf@mail.jurta.org> <83pq9o1f9s.fsf@gnu.org> <09237F12532B42C381CDBC71FA09EA08@us.oracle.com> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org X-Trace: dough.gmane.org 1338227604 26155 80.91.229.3 (28 May 2012 17:53:24 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Mon, 28 May 2012 17:53:24 +0000 (UTC) Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org To: Drew Adams Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon May 28 19:53:23 2012 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 1SZ488-0000yM-Tn for ged-emacs-devel@m.gmane.org; Mon, 28 May 2012 19:53:21 +0200 Original-Received: from localhost ([::1]:43526 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1SZ488-0007Qm-NZ for ged-emacs-devel@m.gmane.org; Mon, 28 May 2012 13:53:20 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:37080) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1SZ484-0007Qf-SL for emacs-devel@gnu.org; Mon, 28 May 2012 13:53:18 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1SZ483-0004SA-6f for emacs-devel@gnu.org; Mon, 28 May 2012 13:53:16 -0400 Original-Received: from mtaout21.012.net.il ([80.179.55.169]:59962) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1SZ482-0004Rt-VA for emacs-devel@gnu.org; Mon, 28 May 2012 13:53:15 -0400 Original-Received: from conversion-daemon.a-mtaout21.012.net.il by a-mtaout21.012.net.il (HyperSendmail v2007.08) id <0M4Q00400UBYK500@a-mtaout21.012.net.il> for emacs-devel@gnu.org; Mon, 28 May 2012 20:53:12 +0300 (IDT) Original-Received: from HOME-C4E4A596F7 ([87.69.210.75]) by a-mtaout21.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0M4Q004PKV0OMW10@a-mtaout21.012.net.il>; Mon, 28 May 2012 20:53:12 +0300 (IDT) In-reply-to: <09237F12532B42C381CDBC71FA09EA08@us.oracle.com> X-012-Sender: halo1@inter.net.il X-detected-operating-system: by eggs.gnu.org: Solaris 10 (beta) X-Received-From: 80.179.55.169 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:150670 Archived-At: > From: "Drew Adams" > Cc: <11381@debbugs.gnu.org>, > Date: Mon, 28 May 2012 10:34:34 -0700 > > The question you (Eli) raise is not specific to isearch or to > delsel. It was relevant to proliferation of the technique discussed there. > But the use of symbol properties, including for function symbols, is nothing > special. It is similar to using attributes or methods with objects in OOP. > What's sometimes missing perhaps is better documentation/discoverability. That's what I was trying to say. "Discoverability" means that someone who calls a function from Org mode (say) that invokes some magic via delsel should be able to understand how that magic happened. I don't see how this can be done today without a lot of digging. If you are hard-pressed for time, this could be a maintenance nightmare. > Can you be more specific about what is missing from the Commentary in delsel.el? It basically doesn't explain anything apart of the fact that the property can have several values. The exact effect of each value is left unclear to the degree of obfuscation. And the names of the values are similarly non-specific. What is needed is a clear description what each value does, and it should be part of the doc string. Right now, this info is only available by reading the code.