[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Solved]
From: |
Memnon Anon |
Subject: |
Re: [Solved] |
Date: |
Sat, 14 Aug 2010 23:18:21 +0200 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/23.2 (gnu/linux) |
Eli Zaretskii <eliz@gnu.org> writes:
> I urge you to reconsider. Sending an email saying that the doc string
> of org-clock-in does not say what value to assign to the SELECT
> argument in a non-interactive call does not need any high level of
> expertise.
Sending the mail does not need expertise. But recognizing if something
really is a deficiency does. Bug reports are great, but creating
"noise" is not; and I really don't want to be a nuisance to the experts
who provide me with so excellent tools. And even if I did recognize a
lack of precision - which requires some knowledge of best practice in
doc strings - I would want to send a patch, which requires even more
knowledge of doc strings in general (= not only seeing what is wrong but
also 'fixing' it).
One way is looking for other docstrings that seem to be "better".
In org, I found lots of functions that are usually called interactively
that have a doc string like the one before.
see eg:
,----[ org-remember.el ]
| (defun org-remember (&optional goto org-force-remember-template-char)
| "Call `remember'. If this is already a remember buffer, re-apply template.
| If there is an active region, make sure remember uses it as initial content
| of the remember buffer.
|
| When called interactively with a \\[universal-argument] \
| prefix argument GOTO, don't remember
| anything, just go to the file/headline where the selected template usually
| stores its notes. With a double prefix argument \
| \\[universal-argument] \\[universal-argument], go to the last
| note stored by remember.
|
| Lisp programs can set ORG-FORCE-REMEMBER-TEMPLATE-CHAR to a character
| associated with a template in `org-remember-templates'."
| (interactive "P")
| (org-require-remember)
| (cond
| ((equal goto '(4)) (org-go-to-remember-target))
| ((equal goto '(16)) (org-remember-goto-last-stored))
`----
I (so far) only found one docstring that seems "better" in this regard:
,----[ org-agenda.el ]
| (defun org-agenda-set-restriction-lock (&optional type)
| "Set restriction lock for agenda, to current subtree or file.
| Restriction will be the file if TYPE is `file', or if type is the
* universal prefix '(4), or if the cursor is before the first headline
| ^^^^^^^^^^^^^^^^^^^^^^
| in the file. Otherwise, restriction will be to the current subtree."
`----
This one says explicitly '(4) is what is tested against.
So should I look for all interactive functions that check against a
universal argument with
(when (equal arg '(4)) ...
and suggest the docstring, which usually only says something like: "When
using \\[universal-argument], ..." to be modified like:
"When using \\[universal-argument] '(4)"? (Of course on a case to case
basis whenever it seems not clear so far.)
> If a doc string does not explain what are the valid values of the
> function's arguments, then that doc string needs to be improved.
> Documenting this is the absolute minimum of any doc string; without
> that, the doc string is useless. It is sometimes okay to omit these
> details if the valid values are clear from the text and the context.
> But I cannot see how someone could claim that the value '(4) could be
> "clear".
Mhhh.
Please have a look at this docstring:
,----[ org-agenda.el ]
| (defun org-agenda-clock-out (&optional arg)
| "Stop the currently running clock."
| (interactive "P")
| (unless (marker-buffer org-clock-marker)
| (error "No running clock"))
| (let ((marker (make-marker)) newhead)
| (org-with-remote-undo (marker-buffer org-clock-marker)
| (with-current-buffer (marker-buffer org-clock-marker)
| (save-excursion
| (save-restriction
| (widen)
| (goto-char org-clock-marker)
| (org-back-to-heading t)
| (move-marker marker (point))
| (org-clock-out)
| (setq newhead (org-get-heading))))))
| (org-agenda-change-all-lines newhead marker)
| (move-marker marker nil)))
`----
This function takes an (optioal) arg, but it is in now way explain what
this arg does.
To tell the truth, in contrast to `org-agenda-clock-in', I do not even
see where this arg is used anywhere in the function...
Should I really file bug reports when I obviously do not understand
whats going on? I don't think so.
Plus: All these points are not really important, because these functions
are meant to be used interactively, what they usually are ... except
when someone wants to bind them to a key with a lambda like in the case
of C-u C-c C-x C-i (org-clock-in) before.
Memnon
P.S.: Cool, I saw you really use the convention to start a new sentence
with <SPC> <SPC>. I never saw anyone really that :)
- Re: Prefix-Arg (non-interactive!) in Info, (continued)
- Re: Prefix-Arg (non-interactive!) in Info, Memnon Anon, 2010/08/13
- Re: Prefix-Arg (non-interactive!) in Info, Andreas Röhler, 2010/08/13
- Re: Prefix-Arg (non-interactive!) in Info, Memnon Anon, 2010/08/13
- Re: Prefix-Arg (non-interactive!) in Info, Eli Zaretskii, 2010/08/13
- [Solved] (was: Prefix-Arg (non-interactive!) in Info), Memnon Anon, 2010/08/13
- Re: [Solved] (was: Prefix-Arg (non-interactive!) in Info), Eli Zaretskii, 2010/08/14
- Re: [Solved],
Memnon Anon <=
- Re: [Solved], Eli Zaretskii, 2010/08/14