From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Richard Stallman Newsgroups: gmane.emacs.devel Subject: Re: docstrings and elisp reference Date: Fri, 09 Jun 2017 23:19:48 -0400 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> Reply-To: rms@gnu.org NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Trace: blaine.gmane.org 1497064863 25098 195.159.176.226 (10 Jun 2017 03:21:03 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sat, 10 Jun 2017 03:21:03 +0000 (UTC) Cc: stephen_leake@stephe-leake.org, drew.adams@oracle.com, emacs-devel@gnu.org To: Etienne =?utf-8?Q?Prud=E2=80=99homme?= Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Jun 10 05:21:00 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 1dJWxP-0006IF-Cq for ged-emacs-devel@m.gmane.org; Sat, 10 Jun 2017 05:20:59 +0200 Original-Received: from localhost ([::1]:57110 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dJWxU-0000fI-JT for ged-emacs-devel@m.gmane.org; Fri, 09 Jun 2017 23:21:04 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:48824) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dJWwa-0000dv-Qk for emacs-devel@gnu.org; Fri, 09 Jun 2017 23:20:09 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dJWwZ-0004FK-Qm for emacs-devel@gnu.org; Fri, 09 Jun 2017 23:20:08 -0400 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:38584) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dJWwG-000404-Ss; Fri, 09 Jun 2017 23:19:48 -0400 Original-Received: from rms by fencepost.gnu.org with local (Exim 4.82) (envelope-from ) id 1dJWwG-0004HR-6Q; Fri, 09 Jun 2017 23:19:48 -0400 In-reply-to: <877f0ln3dx.fsf@x230.lts> (message from Etienne =?utf-8?Q?Pru?= =?utf-8?Q?d=E2=80=99homme?= on Fri, 09 Jun 2017 01:20:26 -0400) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e 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:215548 Archived-At: [[[ To any NSA and FBI agents reading my email: please consider ]]] [[[ whether defending the US Constitution against all enemies, ]]] [[[ foreign or domestic, requires you to follow Snowden's example. ]]] > Emacs Lisp doc strings have support for some of JavaDoc features, but > cannot compare in many things. Many things described in doc strings are > informal and are pretty difficult to extract. For example, we have no > formal way of telling: > - the type of the function return value > - what exceptions can be thrown from the function > - does this function has side effects > - since when it was introduced > - it’s a hook variable > - if the comment includes a file system path in the example What this amounts to is that they are basically similar but JavaDoc has additional features. Those that make sense to add, we can add to the doc strings. > - the type of the function return value That is not crucial in Lisp the way it is in Java. Unlike Java, Lisp does not declare or limit the type of any values. In some cases we document what the type will actually be, using English text. > - what exceptions can be thrown from the function In general, there is no limit to what exceptions can be thrown. In Lisp, that is dynamic. > - does this function has side effects In general, any Lisp function can have side effects. We could define a more systematic way to indicate in doc strings that a certain function has no side effects, that you can assume it preserves the current buffer, or that it preserves the search results. And whatever else could be useful. > - since when it was introduced That does not seem important to me. > - it’s a hook variable We could define a systematic way to indicate this in doc strings. > - if the comment includes a file system path in the example I don't understand what that means. -- Dr Richard Stallman President, Free Software Foundation (gnu.org, fsf.org) Internet Hall-of-Famer (internethalloffame.org) Skype: No way! See stallman.org/skype.html.