Re: docstrings and elisp reference

[Yuri Khan]

On Sat, Jun 10, 2017 at 10:19 AM, Richard Stallman <address@hidden> 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.