3

Is it possible to change the first line of a docstring of a function, without editing the source code of this function? And if, how can I do this?

Background: some packages come with a pretty useless doc string summary. (for example, fci-mode: "Toggle fci-mode on and off.").

Because I have some helper commands, which show this summary, I'd like to exchange the docstring summary of those functions to something more useful (or even translate them to my mother tongue), without touching the source code of those packages.

6

You can access the raw documentation string of a function foo with (documentation 'foo t).

You can set the documentation string of foo with
(put 'foo 'function-documentation "My new docstring.").

The following example shows you how you can exchange the first line of the documentation string:

(defun change-description-line (symbol new-description)
  "Change first line of doc string for SYMBOL to NEW-DESCRIPTION."
  (put symbol 'function-documentation
       (concat new-description
           (let* ((doc (documentation symbol t))
              (pos (cl-position ?\n doc)))
         (and pos (substring doc pos))))))

;;; Usage example:
(unintern 'foo obarray)
(defun foo ()
  "Greetings from function foo.
The real info often is on the second line:-(."
  )

(change-description-line 'foo "New description of foo.")

Note that the symbol property function-documentation overrides the documentation stored in the function object.

To restore the documentation from the function object you can use
(put 'foo 'function-documentation nil)

Alternatively, if you want to re-define foo anyway you can just remove the symbol foo from the global obarray:
(unintern 'foo obarray)

6

In addition to @Tobias's answer, refer to C-hig (elisp)Accessing Documentation

The other notable aspect of dynamic documentation via the function-documentation symbol property (amongst others), is that it can be generated on-demand.

If FUNCTION is a symbol, this function first looks for the ‘function-documentation’ property of that symbol; if that has a non-‘nil’ value, the documentation comes from that value (if the value is not a string, it is evaluated).

e.g. A function-documentation property value of '(foo) will cause the function foo to be called to obtain the documentation, each time it is needed.

  • very interesting – jue Apr 24 at 11:25

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.