Provide explanation why batch functions are implemented as macros

,----
| The functions `org-batch-agenda', `org-batch-agenda-csv', and
| `org-batch-store-agenda-views' are implemented as macros to provide
| a conveniant way for extracting agenda information from the command
| line. The Lisp does not evaluate parameters of a macro call; thus
| it is not necessary to quote the parameters passed to one of those
| functions. E.g. you can write:
|
|   emacs -batch -l ~/.emacs -eval '(org-batch-agenda "a" org-agenda-span 7)'
|
| To export an agenda spanning 7 days. If `org-batch-agenda' would
| have been implemented as a regular function you'd have to quote the
| symbol org-agenda-span. Moreover: To use a symbol as parameter
| value you would have to double quote the symbol.
|
| This is a hack, but it works even when running Org byte-compiled.
`----

lisp/org-agenda.el

@@ -27,6 +27,23 @@
 ;;; Commentary:
 
 ;; This file contains the code for creating and using the Agenda for Org-mode.
+;;
+;; The functions `org-batch-agenda', `org-batch-agenda-csv', and
+;; `org-batch-store-agenda-views' are implemented as macros to provide
+;; a conveniant way for extracting agenda information from the command
+;; line. The Lisp does not evaluate parameters of a macro call; thus
+;; it is not necessary to quote the parameters passed to one of those
+;; functions. E.g. you can write:
+;;
+;;   emacs -batch -l ~/.emacs -eval '(org-batch-agenda "a" org-agenda-span 7)'
+;;
+;; To export an agenda spanning 7 days. If `org-batch-agenda' would
+;; have been implemented as a regular function you'd have to quote the
+;; symbol org-agenda-span. Moreover: To use a symbol as parameter
+;; value you would have to double quote the symbol.
+;;
+;; This is a hack, but it works even when running Org byte-compiled.
+;;
 
 ;;; Code:
 
@@ -2697,7 +2714,6 @@ This ensures the export commands can easily use it."
   (interactive)
   (eval (list 'org-batch-store-agenda-views)))
 
-;; FIXME, why is this a macro?????
 ;;;###autoload
 (defmacro org-batch-store-agenda-views (&rest parameters)
   "Run all custom agenda commands that have a file argument."