From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Yuri Khan Newsgroups: gmane.emacs.devel Subject: Re: docstrings and elisp reference Date: Sat, 10 Jun 2017 15:22:13 +0700 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> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="UTF-8" X-Trace: blaine.gmane.org 1497083001 27603 195.159.176.226 (10 Jun 2017 08:23:21 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sat, 10 Jun 2017 08:23:21 +0000 (UTC) Cc: =?UTF-8?Q?Etienne_Prud=E2=80=99homme?= , Stephen Leake , Drew Adams , Emacs developers To: "rms@gnu.org" Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Jun 10 10:23:14 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 1dJbft-0006a6-NK for ged-emacs-devel@m.gmane.org; Sat, 10 Jun 2017 10:23:13 +0200 Original-Received: from localhost ([::1]:57618 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dJbfv-0003bE-Hn for ged-emacs-devel@m.gmane.org; Sat, 10 Jun 2017 04:23:15 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:58670) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dJbfM-0003b8-0f for emacs-devel@gnu.org; Sat, 10 Jun 2017 04:22:40 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dJbfK-0003ui-QJ for emacs-devel@gnu.org; Sat, 10 Jun 2017 04:22:40 -0400 Original-Received: from mail-wr0-x232.google.com ([2a00:1450:400c:c0c::232]:35868) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1dJbfI-0003u3-Di; Sat, 10 Jun 2017 04:22:36 -0400 Original-Received: by mail-wr0-x232.google.com with SMTP id v111so52362383wrc.3; Sat, 10 Jun 2017 01:22:36 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=mime-version:sender:in-reply-to:references:from:date:message-id :subject:to:cc; bh=3P02L4Rqt4Q1a+wPImrP8g3KGMcXnFNRXoYRXMRGyWc=; b=sHOLB05sSumn6K+Nvh/7kzt23hSb7u1uhcm8AkLx/kTPbXPyP3WswbAuqLu8xak2vF 2LQ6niickhMsRcD1tDibyrNwaENPIv/HFSLHJrdgGyE7tgREG6tXpm1ynLIq92GXYent Ytx6xGz4VZgzccCWhVU6i24+47gDb5X2mhSOvseI4FrnZk+UjzMhdpXauZ2OyZyBhfbc L/dddnOtZdZo8c1BrU37qpzlJ4zdq/GjWTq5Vt+5pVbglqsmjo9ZJOnl0aofba7BvkXS 4K6AbA/H0vYhu0m/uJmeaQINexm84zApEJ3dxLAuiamY280GuFqZAFXnKk9P+4fCyIzV ZVRA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:sender:in-reply-to:references:from :date:message-id:subject:to:cc; bh=3P02L4Rqt4Q1a+wPImrP8g3KGMcXnFNRXoYRXMRGyWc=; b=FuAGViSprKeqXrPOXF7U9U3m2ancwa35YBpLUMgnTZgDw/Q4O1/Ah1Uw8ng3hKL+/b 8Fff9OoR0OBkGZrVkzSibtkX2NmpJBGuA7vgS+9D0ljn/68DDKkJVvRvXlcMkdT1eYKD 7CAb5oC4pKtjO4r9atlOO7NzNZZCgN0ldYglG6lRwmnlfMzWsQ7O0S36A+3ssiEcCvHZ gwU8WP8ca41o0n+SeVyzunrccpCsgH/LCNaE/oRibt/lDAVEbwHotnNYHwroGSlhxFNE U2oTYYzF2wfrh9VaYARoKt7Ljv3lqb6gbXx9vGuuDc359KCFs/jNMublwtNTMCbjYX1I LG/g== X-Gm-Message-State: AKS2vOxFhPBFNsTjvpYq5PnTmu5MbteOhrLTdvN1E0ZLIMe0mMsJsnSl 142Ys9FvM2MBraSUujmvJepStbj6yTKN X-Received: by 10.28.7.16 with SMTP id 16mr2307617wmh.16.1497082954792; Sat, 10 Jun 2017 01:22:34 -0700 (PDT) Original-Received: by 10.223.164.93 with HTTP; Sat, 10 Jun 2017 01:22:13 -0700 (PDT) In-Reply-To: X-Google-Sender-Auth: dlIcG_5BWGVQqDhYanpYDlFfjrQ X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:400c:c0c::232 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:215552 Archived-At: On Sat, Jun 10, 2017 at 10:19 AM, Richard Stallman wrote: > > - 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. And that documentation is immensely helpful. Moreover, I will hazard a guess that any attempt to shoehorn that documentation into a formal type description language will limit its usefulness to readers. As anecdotal evidence, I will offer an example. XML is a hierarchical dynamically-typed data structure, very similar to Lisp S-expressions in terms of capabilities. In order to be able to document and validate permissible constructs, people devised not one but two formal languages: DTD and XML Schema. Of these, the latter is itself XML-based, and thus very appealing to implementors. The resulting schema documents are very verbose and hard to read, even for a trained professional. The programming equivalent of legalese.