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: Tue, 6 Jun 2017 13:36:33 -0700 (PDT) Message-ID: <7acc7d4f-23cc-4b6a-b062-ef92805e465b@default> References: <0BB64F35-233A-471F-B99F-51F96C4E6CCB@gmail.com> <8360g99n07.fsf@gnu.org> <86lgp4q2xa.fsf@stephe-leake.org> 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 1496781442 4733 195.159.176.226 (6 Jun 2017 20:37:22 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Tue, 6 Jun 2017 20:37:22 +0000 (UTC) To: Stephen Leake , emacs-devel Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Tue Jun 06 22:37:17 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 1dILE4-0000za-Rq for ged-emacs-devel@m.gmane.org; Tue, 06 Jun 2017 22:37:16 +0200 Original-Received: from localhost ([::1]:40029 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dILEA-00072y-BT for ged-emacs-devel@m.gmane.org; Tue, 06 Jun 2017 16:37:22 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:52839) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dILDY-00071t-3z for emacs-devel@gnu.org; Tue, 06 Jun 2017 16:36:44 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dILDU-0006Hb-TO for emacs-devel@gnu.org; Tue, 06 Jun 2017 16:36:44 -0400 Original-Received: from userp1040.oracle.com ([156.151.31.81]:31899) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1dILDU-0006FA-Hh for emacs-devel@gnu.org; Tue, 06 Jun 2017 16:36:40 -0400 Original-Received: from aserv0022.oracle.com (aserv0022.oracle.com [141.146.126.234]) by userp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id v56KaaxW010826 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Tue, 6 Jun 2017 20:36:37 GMT Original-Received: from aserv0122.oracle.com (aserv0122.oracle.com [141.146.126.236]) by aserv0022.oracle.com (8.14.4/8.14.4) with ESMTP id v56KaZmH007063 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Tue, 6 Jun 2017 20:36:36 GMT Original-Received: from abhmp0013.oracle.com (abhmp0013.oracle.com [141.146.116.19]) by aserv0122.oracle.com (8.14.4/8.14.4) with ESMTP id v56KaYZd025887; Tue, 6 Jun 2017 20:36:34 GMT In-Reply-To: <86lgp4q2xa.fsf@stephe-leake.org> 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: aserv0022.oracle.com [141.146.126.234] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4.x-2.6.x [generic] [fuzzy] X-Received-From: 156.151.31.81 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:215479 Archived-At: > >> Having a mechanism that generates automatic documentation (a la > >> javadoc) would be extremely valuable. > > > > It could be valuable, but IMO only if we exercise a lot of discipline > > in producing those comments. Because every project which uses this > > methodology that I looked at ends up providing _abysmally_ inadequate > > documentation. >=20 > +1 >=20 > Doc strings are for short reference information for single > functions/variables. >=20 > texinfo docs are for more indepth explanations of several related > functions/features. >=20 > They are complementary; they should not duplicate each other. Yes. And this is not JavaDoc. The Elisp manual is not purely and simply an API reference manual. And now this question is being rehashed again. Everything said this time around has already been said before. Please consult the previous thread, which was already cited. (If you feel you really have something *new* to say, feel free.)