Re: [Solved]

[Memnon Anon]

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 :)