Re: clear-kill-ring function

[Emanuel Berg]

Joost Kremers <joost.m.kremers@gmail.com> writes:

> Note that the doc string should go before the
> (interactive) call ...
>
>    "Clear the kill ring variable"

Docstrings should be either all user-oriented or all
technology ditto. Or both, in different paragraphs.

In general I'd say user-oriented is much better,
especially in the context of an Emacs help screen and
an interactive function, like what we have here.

However, despite being interactive, this function is
all about technology which might motivate some
tech material.

So either

    "Discard all killed text."

or

    "Set `kill-ring' and `kill-ring-yank-pointer'
    to nil."

Or both:

    "Discard all killed text.\n\nI.e., set `kill-ring' and 
`kill-ring-yank-pointer' to nil."

As for "Clear the kill ring variable":

    1. It only explains what happens in terms of
       technology, not why anyone would do that or
       what is gained from a user perspective by doing
       it. (Here, there purpose is unclear - why would
       anyone do this? - perhaps the OP can explain
       the gain of having an interactive function
       do this.)

    2. There are many "kill ring" variables:

           kill-ring
           kill-ring-max
           kill-ring-yank-pointer

       Which one exactly? And if there is a mention of
       a variable, why not give the exact name and put
       it within `whatever' to make it hyperlinked?

    3. `kill-ring-max' is an integer, while
       `kill-ring' and `kill-ring-yank-pointer' are or
       leads to complicated data structures.
       What exactly does "clear" mean? 0, nil, or an
       empty data structure?

-- 
underground experts united
http://user.it.uu.se/~embe8573