From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Stephen Leake Newsgroups: gmane.emacs.devel Subject: Re: docstrings and elisp reference Date: Tue, 06 Jun 2017 15:25:21 -0500 Message-ID: <86lgp4q2xa.fsf@stephe-leake.org> References: <0BB64F35-233A-471F-B99F-51F96C4E6CCB@gmail.com> <8360g99n07.fsf@gnu.org> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: blaine.gmane.org 1496780766 5913 195.159.176.226 (6 Jun 2017 20:26:06 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Tue, 6 Jun 2017 20:26:06 +0000 (UTC) User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.1.91 (windows-nt) To: emacs-devel Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Tue Jun 06 22:26:01 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 1dIL3B-0001Dt-47 for ged-emacs-devel@m.gmane.org; Tue, 06 Jun 2017 22:26:01 +0200 Original-Received: from localhost ([::1]:40004 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dIL3G-0003z4-Im for ged-emacs-devel@m.gmane.org; Tue, 06 Jun 2017 16:26:06 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:50227) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dIL2l-0003yz-3q for emacs-devel@gnu.org; Tue, 06 Jun 2017 16:25:35 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dIL2h-0004Dj-4A for emacs-devel@gnu.org; Tue, 06 Jun 2017 16:25:35 -0400 Original-Received: from smtp129.dfw.emailsrvr.com ([67.192.241.129]:57536) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1dIL2g-00048Y-Ux for emacs-devel@gnu.org; Tue, 06 Jun 2017 16:25:31 -0400 Original-Received: from smtp29.relay.dfw1a.emailsrvr.com (localhost [127.0.0.1]) by smtp29.relay.dfw1a.emailsrvr.com (SMTP Server) with ESMTP id 3B9AE4032E for ; Tue, 6 Jun 2017 16:25:24 -0400 (EDT) X-Auth-ID: board-president@tomahawk-creek-hoa.com Original-Received: by smtp29.relay.dfw1a.emailsrvr.com (Authenticated sender: board-president-AT-tomahawk-creek-hoa.com) with ESMTPSA id E085A402E7 for ; Tue, 6 Jun 2017 16:25:23 -0400 (EDT) X-Sender-Id: board-president@tomahawk-creek-hoa.com Original-Received: from Takver4 (76-218-37-33.lightspeed.kscymo.sbcglobal.net [76.218.37.33]) (using TLSv1.2 with cipher AES128-GCM-SHA256) by 0.0.0.0:587 (trex/5.7.12); Tue, 06 Jun 2017 16:25:24 -0400 In-Reply-To: <8360g99n07.fsf@gnu.org> (Eli Zaretskii's message of "Tue, 06 Jun 2017 18:03:36 +0300") X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x [fuzzy] X-Received-From: 67.192.241.129 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:215477 Archived-At: Eli Zaretskii writes: >> From: Jean-Christophe Helary >> Date: Tue, 6 Jun 2017 14:10:19 +0900 >> >> 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. +1 Doc strings are for short reference information for single functions/variables. texinfo docs are for more indepth explanations of several related functions/features. They are complementary; they should not duplicate each other. -- -- Stephe