Add examples to elisp method documentation

Add examples to elisp method documentation

[Ruslan Kiselev]

Hopefully this is the correct place to aks for this. I'm relatively new to
Emacs/Elisp. It would be extremely helpful if at least some Elisp
function docs included examples.

For example, (describe-function 'let) returns the following:

    let is a special form in `C source code'.

    (let VARLIST BODY...)

    Bind variables according to VARLIST then eval BODY.
    The value of the last form in BODY is returned.
    Each element of VARLIST is a symbol (which is bound to nil)
    or a list (SYMBOL VALUEFORM) (which binds SYMBOL to the value of VALUEFORM).
    All the VALUEFORMs are evalled before any symbols are bound.

Addition of an example would make it easier for beginners to
understand/use:

  let is a special form in `C source code'.

  (let VARLIST BODY...)

  Bind variables according to VARLIST then eval BODY.
  The value of the last form in BODY is returned.
  Each element of VARLIST is a symbol (which is bound to nil)
  or a list (SYMBOL VALUEFORM) (which binds SYMBOL to the value of VALUEFORM).
  All the VALUEFORMs are evalled before any symbols are bound.

  Example:

  (let ((apple "apple")
       (orange "orange")
       (banana "banana"))
       (message (format "Fruits: %s %s %s" apple orange banana)))

I'd like to create a branch and work on adding snippets like this. It
would help me learn Emacs's funcs and IMO help future Emacs users.

Re: Add examples to elisp method documentation

[Michael Heerdegen]

Ruslan Kiselev <voltecrus@gmail.com> writes:

> Hopefully this is the correct place to aks for this. I'm relatively
> new to Emacs/Elisp.

Welcome!

> It would be extremely helpful if at least some Elisp function docs
> included examples.

Did you have a look at the Elisp (info) manual?  That's the canonical
place where examples are given and things are described in a broader
way.  Docstrings are intentionally concise.

There is also an introduction into Emacs Lisp which offers more examples
for basic stuff like `let'.

You can read these manuals from within Emacs with the info reader (C-h i
etc.)  There is even a hotkey to search the Elisp manual for
documentation about any specific command/function/option/variable
(i.e. symbol): C-h S.

All of these are part of the Emacs distribution.


If you nevertheless find things under-documented, please send a bug
report (preferably with M-x report-emacs-bug).  You can include
patches with suggestions of course.


Regards,

Michael.