From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Nikolay Kudryavtsev Newsgroups: gmane.emacs.devel Subject: Re: docstrings and elisp reference Date: Sat, 10 Jun 2017 14:36:12 +0300 Message-ID: <1f0a4527-e669-a618-8864-baf9ec4c27e0@gmail.com> 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> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 8bit X-Trace: blaine.gmane.org 1497094627 17186 195.159.176.226 (10 Jun 2017 11:37:07 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sat, 10 Jun 2017 11:37:07 +0000 (UTC) User-Agent: Mozilla/5.0 (Windows NT 10.0; WOW64; rv:52.0) Gecko/20100101 Thunderbird/52.1.1 To: Jean-Christophe Helary , emacs-devel Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Jun 10 13:37:03 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 1dJehQ-00044J-HC for ged-emacs-devel@m.gmane.org; Sat, 10 Jun 2017 13:37:00 +0200 Original-Received: from localhost ([::1]:58015 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dJehV-0001Gy-RQ for ged-emacs-devel@m.gmane.org; Sat, 10 Jun 2017 07:37:05 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:59916) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dJego-0001Gr-Ek for emacs-devel@gnu.org; Sat, 10 Jun 2017 07:36:23 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dJegl-0008G9-Ci for emacs-devel@gnu.org; Sat, 10 Jun 2017 07:36:22 -0400 Original-Received: from mail-lf0-x230.google.com ([2a00:1450:4010:c07::230]:34804) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1dJegl-0008Fp-5Q for emacs-devel@gnu.org; Sat, 10 Jun 2017 07:36:19 -0400 Original-Received: by mail-lf0-x230.google.com with SMTP id v20so37585153lfa.1 for ; Sat, 10 Jun 2017 04:36:17 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:subject:to:references:message-id:date:user-agent:mime-version :in-reply-to:content-transfer-encoding:content-language; bh=3eqU73EBQPfjafOWW0uFz7X8ct9kZmSytV3P27bUoBk=; b=So7sgXy+xp4WTs272a5TEES+kW5lJcWYTuCJ+FSy1esHqt5zb+Udw1MFGp0MX8p+aM tGaDCHStXY67IkdybcnEfu8Fb6eRZQ4/4inhfW9v2gnV4Hx7Td64E3ha2hjgVjWsyz75 5VXrtGmQiZCfxTcQBteFlD89iTTlabyItWaVbb20VSaBS3L2ZGatRC0FbRjXWPrhNakJ L6mcySLC3jKAXtxWgMZHv4X0cG76SgamYuJNga0T8egPHx0Rxv1HmSgLXqDoPESy9nyN i69YPZuIvwpnfrF9GIN1uNP1ZCtdVhdWO4jC30uxT1Ll4malTsv6ECmSbCoXjKtsbRC5 Zneg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:subject:to:references:message-id:date :user-agent:mime-version:in-reply-to:content-transfer-encoding :content-language; bh=3eqU73EBQPfjafOWW0uFz7X8ct9kZmSytV3P27bUoBk=; b=knbFYtS4cFxEpTvg2PSqkH8l7aXMXO10E72ucZ00y39Dxy7S8Ajizcn5kVHzBRax7z 2BqLP1Tl4Wt+xlOnNdk+Dv3FZp3NaeO99Sl/5xelJDZWoonBHLD5BGR+k7BGchTGQ8w6 mdiB5z6SVtaDRj0rN7XSROtvwxsMzD+99Oba60Vf7JsaB9GbywoYZxi4XRdktplk0rDN AkN8Al+PNE2vCpY2lkq7q9nOzD6x4XytfQt5xNe2IcyItd2b+UR/m8uu7zhkOSulXmD6 byK63HoXg5/UKXV8rOA+IvEKTZ0tJEHo+Vdwx3STpcYsHrCurvS6aVFx6AdeVsNKLSu8 Qfjw== X-Gm-Message-State: AODbwcCTigdg13GwWAe71sZbXnEs/AFcVsI6EJxMYUfCQkKIJaJxzwxm 6MJxU+hfedz3rv1Y X-Received: by 10.46.6.2 with SMTP id 2mr933567ljg.136.1497094575763; Sat, 10 Jun 2017 04:36:15 -0700 (PDT) Original-Received: from [192.168.199.6] (broadband-95-84-209-126.moscow.rt.ru. [95.84.209.126]) by smtp.gmail.com with ESMTPSA id r38sm1005294lfi.4.2017.06.10.04.36.14 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Sat, 10 Jun 2017 04:36:14 -0700 (PDT) X-Google-Original-From: Nikolay Kudryavtsev In-Reply-To: <54A01FC0-6692-411D-91CB-764402C7BF14@gmail.com> Content-Language: en-US X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4010:c07::230 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:215554 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. 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. 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". 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. I'm not saying that it's impossible to build a better documentation system than we currently have in info. It's just a massive investment that would at best be a very slight improvement. As a practical example I installed Zeal and downloaded MySQL manual for it. It has different indexes, but there is no table of contents(1). Let's say I want to calculate a logarithm. I go by function index and find one of the log functions. Luckily that's the full MySQL Reference Manual and not some javadoc abomination and it provides all log functions within the same context, and that within a broader context of math functions. Also I can't search the whole manual at once, only indexes or a single chapter(2). And it's worth noting that the search is just a dumb text search(just as in info) and not some natural language processing one as proposed by Etienne Prud’homme in this thread. So, due to 1 and 2 Zeal is not superior to info in usability, while discoverability is a feature of the material and not presentation. -- Best Regards, Nikolay Kudryavtsev