How does (org-agenda-todo arg) work? What does the argument mean?

Question

By trial and error I have found that in org-agenda (org-agenda-todo 'done) marks the entry at point as "DONE".

Can you explain why?

How can I modify the argument to the org-agenda-todo function (or which other function should I use) to mark the entry some other state, e.g. "WAITING"?

Answer 1

org-agenda-todo calls the org-todo function interactively and in doing so, the it passes its own argument as it is to org-todo¹.

From C-h f org-todo, you will get a complete understanding of what the values of ARG mean to org-todo (and org-agenda-todo):

org-todo is an interactive compiled Lisp function in `org.el'.

(org-todo &optional ARG)

Change the TODO state of an item.
The state of an item is given by a keyword at the start of the heading,
like
     *** TODO Write paper
     *** DONE Call mom

The different keywords are specified in the variable ‘org-todo-keywords’.
By default the available states are "TODO" and "DONE".
So for this example: when the item starts with TODO, it is changed to DONE.
When it starts with DONE, the DONE is removed.  And when neither TODO nor
DONE are present, add TODO at the beginning of the heading.

With C-u prefix arg, use completion to determine the new state.
With numeric prefix arg, switch to that state.
With a double C-u prefix, switch to the next set of TODO keywords (nextset).
With a triple C-u prefix, circumvent any state blocking.
With a numeric prefix arg of 0, inhibit note taking for the change.
With a numeric prefix arg of -1, cancel repeater to allow marking as DONE.

When called through ELisp, arg is also interpreted in the following way:
‘none’             -> empty state
""(empty string)  -> switch to empty state
‘done’             -> switch to DONE
‘nextset’          -> switch to the next set of keywords
‘previousset’      -> switch to the previous set of keywords
"WAITING"         -> switch to the specified keyword, but only if it
                     really is a member of ‘org-todo-keywords’.

---

¹ I learned the above by looking at the source code of org-agenda-todo.

So it might be useful to email emacs-orgmode@gnu.org with a request to add more information to the doc-string of org-agenda-todo.. Something along the lines of "Refer to the documentation of org-todo to learn how ARG is used.".