Re: docstrings and elisp reference

[Richard Stallman]

[[[ 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.