From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.devel Subject: RE: docstrings and elisp reference Date: Sat, 10 Jun 2017 07:26:25 -0700 (PDT) Message-ID: References: <0BB64F35-233A-471F-B99F-51F96C4E6CCB@gmail.com> <8360g99n07.fsf@gnu.org> <86lgp4q2xa.fsf@stephe-leake.org> <7acc7d4f-23cc-4b6a-b062-ef92805e465b@default> <878tl3rz38.fsf@x230.lts> <877f0ln3dx.fsf@x230.lts> <83poed7i4t.fsf@gnu.org> <83o9tx7b7d.fsf@gnu.org> <83mv9h73o1.fsf@gnu.org> <83lgp16zpw.fsf@gnu.org> <87h8zpge1y.fsf@x230.lts> <54A01FC0-6692-411D-91CB-764402C7BF14@gmail.com> <1f0a4527-e669-a618-8864-baf9ec4c27e0@gmail.com> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Trace: blaine.gmane.org 1497104805 10911 195.159.176.226 (10 Jun 2017 14:26:45 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sat, 10 Jun 2017 14:26:45 +0000 (UTC) To: Nikolay Kudryavtsev , Jean-Christophe Helary , emacs-devel Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Jun 10 16:26:40 2017 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1dJhLb-0002PU-6e for ged-emacs-devel@m.gmane.org; Sat, 10 Jun 2017 16:26:39 +0200 Original-Received: from localhost ([::1]:58677 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dJhLd-0004oc-Vo for ged-emacs-devel@m.gmane.org; Sat, 10 Jun 2017 10:26:42 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:58699) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dJhLX-0004oW-ML for emacs-devel@gnu.org; Sat, 10 Jun 2017 10:26:36 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dJhLT-0005dl-KY for emacs-devel@gnu.org; Sat, 10 Jun 2017 10:26:35 -0400 Original-Received: from aserp1040.oracle.com ([141.146.126.69]:28970) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1dJhLT-0005d0-Am for emacs-devel@gnu.org; Sat, 10 Jun 2017 10:26:31 -0400 Original-Received: from userv0022.oracle.com (userv0022.oracle.com [156.151.31.74]) by aserp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id v5AEQQAI031253 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Sat, 10 Jun 2017 14:26:27 GMT Original-Received: from userv0122.oracle.com (userv0122.oracle.com [156.151.31.75]) by userv0022.oracle.com (8.14.4/8.14.4) with ESMTP id v5AEQQIw025976 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Sat, 10 Jun 2017 14:26:26 GMT Original-Received: from abhmp0002.oracle.com (abhmp0002.oracle.com [141.146.116.8]) by userv0122.oracle.com (8.14.4/8.14.4) with ESMTP id v5AEQQve001760; Sat, 10 Jun 2017 14:26:26 GMT In-Reply-To: <1f0a4527-e669-a618-8864-baf9ec4c27e0@gmail.com> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 12.0.6767.5000 (x86)] X-Source-IP: userv0022.oracle.com [156.151.31.74] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4.x-2.6.x [generic] [fuzzy] X-Received-From: 141.146.126.69 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 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" Xref: news.gmane.org gmane.emacs.devel:215560 Archived-At: > What's important to understand here is that docstring documentation > is of very limited use. This applies to both Emacs docstrings and > everything created by javadoc and its cousins. >=20 > Let's say I want to do something with an API that I have no prior > knowledge of and I have only the docstring documentation. I start by > searching docstrings for something that looks vaguely useful for solving > the problem at hand. Would the first thing(be it a class, or a function) > I found be the optimal solution? > > Maybe there's actually a more > specialized version of this function that better suits my case. Or maybe > it's the opposite - I stumbled into a specialized function, where the > broader one is more suited for me. There's no way to know until you read > everything that looks even slightly important. >=20 > Because of this, the documentation needs some glue, that puts separate > elements into a proper context. Docstrings are incapable of solving this > problem yet. You can't just have docstrings that go "if you find this > function useful, maybe you actually need this-other-function or maybe > this-totally-other-function". >=20 > The key word here is _discoverability_. Because of this, you can't just > dispose for example of Elisp manual, since it's exactly that rug that > ties the room together. +1. Plus: the source code - in particular, Lisp. That's the glue behind the glue and the single source of information and truth. (Well, not quite single - see C.) A typical such quest might lead from one or more doc strings to the Elisp manual, and then to source code - to find the most useful functions and variables to use, or to find parts of the code that are enlightening or useful for constructing new code for the job. Or it might lead from the Elisp manual to one or both of the other sources of such info. Or it might lead from a single doc string to the source code. Or back & forth. All three are useful: doc strings, Elisp manual, source code. They overlap, but they also complement each other, sometimes in terms of information content but mainly in terms of presentation, audience, and means of access. It's all in the source code, but the other, help, features often facilitate discoverability and improve understanding. Similarly, other help commands and functions: apropos etc. Yes, Java source code is also consultable. But I think that the boost that you get from combining the various information sources that Emacs offers is something more. I don't think that JavaDoc (especially typical JavaDoc!) plus source code gives you what you get with Emacs. Partly that is due to Lisp being what Lisp is, perhaps, but it is also probably due to the ubiquitous and fine-scale attachment of doc/help to code and even to Lisp symbols. The comment above about "typical JavaDoc" is really meant to emphasize this other aspect of Emacs help: It is good not just because the constructs of doc strings and manual _exist_ but because key people in Emacs development have long insisted on their importance. Just being able to attach doc strings or create JavaDoc is not enough. You also need a commitment to using them to create good help. Good help does not fall from the sky. It does not come for free, generated from the source code. Why? Because part of the job of coming up with good help involves addressing the possible audiences, contexts and use cases. Unless and until info about that is encoded in the source code, it needs to be added. (And encoding it in the source code would involve the same "user documentation" work.)=20 IMHO, that commitment is the most important factor - the glue behind the glue. Let's hope it continues. There is no substitute for careful human time and clear eyes devoted to help/doc. No degree of "reuse" or generation of deliverables can substitute for that. Tools are fine, but they don't replace paying attention.