From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Stefan Monnier Newsgroups: gmane.emacs.devel Subject: Re: public APIs and private ones (Re: `C-h v' may offer too many symbols) Date: Fri, 11 Mar 2011 15:28:50 -0500 Message-ID: References: <87y64mkdu3.fsf@lifelogs.com> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: dough.gmane.org 1299882473 1766 80.91.229.12 (11 Mar 2011 22:27:53 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Fri, 11 Mar 2011 22:27:53 +0000 (UTC) Cc: lekktu@gmail.com, tzz@lifelogs.com, emacs-devel@gnu.org To: Kenichi Handa Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Mar 11 23:27:48 2011 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1PyAoG-00068I-CG for ged-emacs-devel@m.gmane.org; Fri, 11 Mar 2011 23:27:48 +0100 Original-Received: from localhost ([127.0.0.1]:39165 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1PyAoF-0002vl-On for ged-emacs-devel@m.gmane.org; Fri, 11 Mar 2011 17:27:47 -0500 Original-Received: from [140.186.70.92] (port=41593 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1PyAoA-0002va-Mm for emacs-devel@gnu.org; Fri, 11 Mar 2011 17:27:43 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1PyAo9-0000Kz-Lk for emacs-devel@gnu.org; Fri, 11 Mar 2011 17:27:42 -0500 Original-Received: from tomts5-srv.bellnexxia.net ([209.226.175.25]:46262) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1PyAo9-0000Kt-AG for emacs-devel@gnu.org; Fri, 11 Mar 2011 17:27:41 -0500 Original-Received: from toip4.srvr.bell.ca ([209.226.175.87]) by tomts5-srv.bellnexxia.net (InterMail vM.5.01.06.13 201-253-122-130-113-20050324) with ESMTP id <20110311222739.BBHY18540.tomts5-srv.bellnexxia.net@toip4.srvr.bell.ca> for ; Fri, 11 Mar 2011 17:27:39 -0500 X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: AvsEAEosek1GHsU+/2dsb2JhbACmNXjCYoViBIUp Original-Received: from bas1-montreal07-1176421694.dsl.bell.ca (HELO ceviche.home) ([70.30.197.62]) by toip4.srvr.bell.ca with ESMTP; 11 Mar 2011 17:27:39 -0500 Original-Received: by ceviche.home (Postfix, from userid 20848) id 9527666710; Fri, 11 Mar 2011 15:28:50 -0500 (EST) In-Reply-To: (Kenichi Handa's message of "Fri, 11 Mar 2011 13:31:30 +0900") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.0.50 (gnu/linux) X-detected-operating-system: by eggs.gnu.org: Solaris 8 (1) X-Received-From: 209.226.175.25 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:137128 Archived-At: > This is a little bit different topic, but shouldn't we have > a way to distinguish functions/macros/variables for public > API from those for internal (i.e. only within a specific > package) use only. I try to follow the convention that I use "--" for functions/macros/variables internal to . It's just a convention and it's currently very little used, but I encourage people to use it more systematically. We also use the "internal-" prefix for things that are "internal to Emacs core" (typically functions exported from C meant only for use in subr.el, tho I also used it in lexbind for operations that only appear in some intermediate form of the code manipulated by the compiler). > For instance, as basic-save-buffer-1 is just a helper function of > basic-save-buffer, there's no need to list it by C-h f TAB. I'm not completely sure if it would be a good idea: I also use C-h f to find such internal functions. > In addition, and this is more important, such a distinguishment makes > it easier to maintain a package. Fully agreed. It also makes it easier for users of the package to figure out what are the intended entry points. Stefan