Emacs Self Documentation

Emacs has an interesting means of documenting itself. When you declare a function or variable, you can include a documentation string, similar to a JavaDoc comment. For example

  (defun cleanup-whitespace ()
    "Clean up a buffer's whitespace by deleting any trailing whitespace on lines
  and converting tabs to spaces."
    (interactive)
    (save-excursion
      (goto-char (point-min))
      (while (re-search-forward "[ \t]+$" nil t)
        (delete-region (match-beginning 0) (match-end 0)))
      (goto-char (point-min))
      (if (search-forward "\t" nil t)
          (untabify (1- (point)) (point-max))))
    nil)

Once you define this, you can read the documentation by calling (describe-function 'cleanup-whitespace) or typing C-h f cleanup-whitespace RET:

 cleanup-whitespace is an interactive Lisp function.
 (cleanup-whitespace)

 Clean up a buffer's whitespace by deleting any trailing whitespace on lines
 and converting tabs to spaces

This tells us that cleanup-whitespace takes no arguments, and describes its function.

Sorry to be obtuse, but how does this blerb tell us that this function takes no arguments? It says, "on lines," but there isn't any other explanation. Does it apply to the entire buffer? Can it be made to apply only to a marked area? Curious non-Lispers want to know.

On the second line. It shows you how to run this function, and you can see that there are no parameters in the parenthesis.

Okay, but how do I know that? Do I "just know it?" It's some sort of convention, right? That's one of the major problems I ran into with the whole Lisp community. Everybody just assumed that everybody else knew all the phunky conventions and there was nothing anywhere to get me started. I was really lost.

Many of the interactive functions whose help is aimed at end users have more verbose help than this. Try "C-h k C-x $" for an example that likes a prefix argument, then "C-h k C-h k" to find out what you just asked for (help on keystroke).

You can get extra context by looking at different parts of the system - you build a view of how things were put together, and this is made easier because Emacs is fairly consistent. Granted, though, this is probably easier for people who ThinkLikeAprogrammer?.

For example, when using TabCompletion to find help on a function: "C-h f count TAB TAB" you will notice count-lines-region and count-lines-page (these are interactive functions) and count-if (this is not an interactive function). If you wanted tab completion on commands rather than functions, you would probably use "M-x count TAB TAB" instead.

(Well, I was trying to show how you might get the knowledge of these conventions, but instead I have demonstrated nicely that it is quite complex. I'm afraid I can't tell you how I figured it out because I don't know, I can offer only recursive MetaLearning.) -- MatthewAstley

---

When you're trying to find documentation but can't remember the name of the function or variable you want, you can also regular-expression search on function names, variable names, and even variable contents. It typically takes only a few seconds to find a function definition if you know what you're looking for (or can find it with TabCompletion).

This is what they mean by "self-documenting editor".

But there is more to it than that. See ProgrammingValueSystem for something related on an abstract level. -- ma

---

Emacs has taken this feature from Lisp environments where it is pretty standard. In a CommonLisp development environment you have the same feature for all functions, variables etc. defined by your implementation and any add-ons you load.

Python has docstrings as well.

We have also added this feature to the DistEl Emacs-based Erlang IDE. Since Erlang lacks docstrings, we use a surprisingly useful heuristic: build a doc database by scanning all source files, and treating a comment appearing directly before a function as the documentation for that function. For a large source tree (complete Erlang/OTP system plus a large custom product), it only takes a few seconds to scan the sources. We then keep the database cached, with an option to rebuild it (by giving a numeric prefix argument to the Emacs commands.) 417 lines of Erlang and EmacsLisp well spent! -- LukeGorrie

---

CategoryEmacs