docstrings (was: Re: Add-on USB custom keypads)

[Emanuel Berg]

Tim Johnson <tim@akwebsoft.com> writes:

> I grew up on a homestead. We just made
> things work.

Indeed. I have the gene as well. Make it work,
by out working the opposition...

> I find the whole concept of lisp (as in
> elisp, racket, clojure) associates with the
> minimalist (homestead) approach of right and
> left parens to be a study in
> simplistic beauty.

I prefer the Lisp syntax and extra power
compared to other languages - e.g., code as
data, data as code, almost complete freedom, no
explicit types, and many other examples - from
a practical point tho the thing I like the most
is the integration with Emacs (the quick fix)
so you immediately can see the result of your
actions. It is the most pleasant way of
programming. I have sort of the same in the
shell (zsh) but not exactly as the
infrastructure is much less developed, you have
to reload the code manually (even tho it takes
zero time, still annoying compared to the eval
of a single defun). Even so, compared to LaTeX
and C and such giants with feet of clay, the
shell seems like a bunch of thin clouds...

> And as for emacs, the help system is awesome,
> maybe the best thing. I also use python.
> Docstrings rock!

Indeed. Good example of infrastructure. I like
focusing on the form, making it perfect, and
then wait for the data to "catch up"...

It always feels like a loss of prestige when
you have to Google something like some mere
plebeian. To have a uniform interface is great.

Only sometimes the docstrings themselves are
incomplete - for example, not that seldom, the
function comes with arguments that aren't
mentioned in the docstring.

Here is an example of a bad docstring in
several ways:

(transpose-sexps ARG)

    Like M-t but applies to sexps.
    Does not work on a sexp that point is in the middle of
    if it is a list or string.

-- 
underground experts united .... http://user.it.uu.se/~embe8573
Emacs Gnus Blogomatic ......... http://user.it.uu.se/~embe8573/blogomatic
                   - so far: 48 Blogomatic articles -