From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Drew Adams" Newsgroups: gmane.emacs.bugs Subject: bug#8682: 24.0.50; doc strings of `isearch-mode', `isearch-forward', etc. Date: Fri, 15 Jul 2011 11:30:33 -0700 Message-ID: References: <5DED13DA31E94AF9BF6B244A80E299D4@us.oracle.com> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="iso-8859-1" Content-Transfer-Encoding: quoted-printable X-Trace: dough.gmane.org 1310757899 30151 80.91.229.12 (15 Jul 2011 19:24:59 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Fri, 15 Jul 2011 19:24:59 +0000 (UTC) Cc: 'Lars Magne Ingebrigtsen' , 8682@debbugs.gnu.org To: "'Juanma Barranquero'" Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Fri Jul 15 21:24:55 2011 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([140.186.70.17]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1Qho0M-00081Z-SG for geb-bug-gnu-emacs@m.gmane.org; Fri, 15 Jul 2011 21:24:55 +0200 Original-Received: from localhost ([::1]:51841 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Qho0L-0004eN-W3 for geb-bug-gnu-emacs@m.gmane.org; Fri, 15 Jul 2011 15:24:54 -0400 Original-Received: from eggs.gnu.org ([140.186.70.92]:54231) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QhnAJ-0007LK-9J for bug-gnu-emacs@gnu.org; Fri, 15 Jul 2011 14:31:10 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1QhnAF-0000E0-8t for bug-gnu-emacs@gnu.org; Fri, 15 Jul 2011 14:31:06 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:53933) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QhnAF-0000Dm-0z for bug-gnu-emacs@gnu.org; Fri, 15 Jul 2011 14:31:03 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.69) (envelope-from ) id 1QhnAE-0004Tw-10; Fri, 15 Jul 2011 14:31:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: "Drew Adams" Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-To: owner@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 15 Jul 2011 18:31:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 8682 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: notabug Original-Received: via spool by 8682-submit@debbugs.gnu.org id=B8682.131075465417214 (code B ref 8682); Fri, 15 Jul 2011 18:31:01 +0000 Original-Received: (at 8682) by debbugs.gnu.org; 15 Jul 2011 18:30:54 +0000 Original-Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1QhnA5-0004Ta-TB for submit@debbugs.gnu.org; Fri, 15 Jul 2011 14:30:54 -0400 Original-Received: from acsinet15.oracle.com ([141.146.126.227]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1QhnA3-0004TO-E1 for 8682@debbugs.gnu.org; Fri, 15 Jul 2011 14:30:52 -0400 Original-Received: from acsinet22.oracle.com (acsinet22.oracle.com [141.146.126.238]) by acsinet15.oracle.com (Switch-3.4.4/Switch-3.4.4) with ESMTP id p6FIUhct001293 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Fri, 15 Jul 2011 18:30:45 GMT Original-Received: from acsmt357.oracle.com (acsmt357.oracle.com [141.146.40.157]) by acsinet22.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id p6FIUgmd017093 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Fri, 15 Jul 2011 18:30:43 GMT Original-Received: from abhmt101.oracle.com (abhmt101.oracle.com [141.146.116.53]) by acsmt357.oracle.com (8.12.11.20060308/8.12.11) with ESMTP id p6FIUbIZ017891; Fri, 15 Jul 2011 13:30:37 -0500 Original-Received: from dradamslap1 (/10.159.40.132) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Fri, 15 Jul 2011 11:30:37 -0700 X-Mailer: Microsoft Office Outlook 11 In-Reply-To: Thread-Index: AcxDEDQgLiB5qhYHTqKMs0xNSXO18AAA96qg X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6109 X-Source-IP: acsinet22.oracle.com [141.146.126.238] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A090206.4E208755.0125:SCFMA922111,ss=1,re=-4.000,fgs=0 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list Resent-Date: Fri, 15 Jul 2011 14:31:02 -0400 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) X-Received-From: 140.186.70.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:49207 Archived-At: > > "Internal" functions too deserve doc strings, in general. > > > > And nothing in Emacs is truly "internal". =A0Emacs=20 > > purposefully documents itself, at all levels. =A0That documentation > > is available to all users interactively. >=20 > Of course there are internal elisp functions. Many of them even use a > convention of having two consecutive dashes in the name to mark that > they are internal, but not all. >=20 > And what makes them internal is that they are an implementation detail > and could be removed, or changed beyond all recognition, at any > moment. Documenting them past the simple "This is an internal > function" leads the user-developer to falsely believe that they are > part of the interface, but they are not. Otherwise, nothing could ever > be changed but painstakingly and with lot of ugly compatibility code. > Which is fine for the advertised interfaces, but not for every single > function in every single package in lisp/**/*.el. >=20 > First someone asks to document them all, then s/he will use them in > some package, and finally s/he will complain harshly when they are > deleted in some future release. Better to say clearly: don't do that, > or do it under you own responsability, after looking at the code, and > knowing full well that if you do you'll likely need to workaround > changes in the future. I actually agree with most of what you wrote, Juanma. And well put. I nevertheless maintain that nothing in Emacs is "_truly_" internal. And that even "internal" functions deserve doc strings, in general. Nothing is truly internal because Emacs is open. More than that - it is intentionally, proudly, exceptionally, emphatically, in-your-face open. = Emacs _wants_ to expose itself, at all levels, to _anyone_ interested. It is = the self-documenting editor. There is no rigid developer/user dichotomy. This is the essential contribution of Emacs (and GNU). We say = "self-documenting AND customizable/modifiable", but the former - more generally open = source code, implies the latter (modifiable). This is to be contrasted with non-free software, where everything that is not advertised via an external API = _is_ truly internal. That nothing is truly internal in Emacs does not preclude those = responsible for the Emacs mainline development from wanting to let users know that = function XYZ is "internal" in the sense that it is better for them not to count on = the current behavior, or the implementation, remaining the same in the = future. That is orthogonal to doc, in general (and please note when I say "in = general", like "truly"). It is not because we want to convey the message that a = function or variable is internal in the sense that it might easily be changed, = that we should not, in general, document that function or variable. Emacs code is open. Doc strings are like easy-to-get-to code comments - = and intentionally so. Instead of digging into the source code to see what a function's parameters and purpose/effect/use are, you can just hit `C-h = f'. But not all code comments, of course. Only those comments that describe = what a thing is for and what its interface (e.g. signature) is. Information = about implementation, which can be found in some code comments, is generally = not appropriate for doc strings. That is another part of the raison d'etre = of doc strings: describe just the API and purpose/effect/use, not the = implementation. And not documenting some internal function does _not_ obviate the = potential problem you cite, of users using it and unwisely expecting it not to = change etc. On the contrary, documentation can, in addition to describing the = parameters and purpose, explicitly point out that the function is likely to be changed = easily. Or as you put it: > Better to say clearly: don't do that, or do it under you own > responsability, after looking at the code, and knowing full > well that if you do you'll likely need to workaround > changes in the future. Almost right, but it is not either/or. What's wrong is your "Better = to". Better to document the function AND say that it might well change = ("internal"). This is open software - we don't win by trying to hide things or get = people to not notice them. Ignorance or misunderstanding about a function or variable is no Chinese = wall against misuse of it. Quite the contrary. > (I'm not talking about the specific changes in this bug thread Which is what we should get back to - specifics about _these_ doc = strings. Still, the general discussion can be useful, since "internal" seems to = be the excuse more and more for not documenting things correctly. No sense = fixing an incorrect statement, since a function is "internal". No sense = documenting a function at all, since it is "internal". There are a wide range of "internal" functions and variables. In = general, we should improve their doc and, in some cases, the code comments. An excuse such as `no user should care about this unless they are = hacking the Isearch code' ("if you're not an isearch hacker, you'll never see it") = is misguided. _Any_ user potentially hacks Isearch code. Not in the = distributed Emacs sources (isearch.el) perhaps, but in user code. The goal should not be to discourage Emacs users from borrowing, = adapting, hacking the Isearch code or any other Emacs source code. Quite the = contrary. This is what Emacs is about. It is the self-documenting, customizable = editor. It is fine to let users know that a given function might change. It is = not fine to try to discourage its use or reuse by obfuscating it or not helping = to make clear what it does. It's just code, and code wants to be copied, = changed, and reused. Isearch should make itself clear to users of all stripes, facilitating = their use, reuse, adaptation, and (who knows?) improvement or extension. Just = as we should make the code clear to facilitate the job of Emacs Dev = maintainers, so we should make it clear for Emacs users. And users are a larger and more = varied group than Emacs Dev. They deserve clear, well commented, well = documented code. This is regardless of the internal needs of Emacs Dev itself. It's not = about the bureaucracy (volunteer or not, and I include myself here) that = serves the people - it's about serving the people. It's not (only or mainly) about = making life easier for Emacs Dev. That's only a subsidiary requirement/goal. Yes, there are reasons for some functions to be more or less internal, = subject to unplanned implementation/interface change, etc. There are not often = reasons to not document what a function does and what its parameters are. Emacs source code is for everyone. When writing it, including its doc, = the target should be Emacs users, not just the code author or the relatively = small group of Emacs Dev maintainers. Yes, this is a radically different = perspective from non-free software development. We have met the user, and s?he is = us - and more.