[elpa] externals/org 080710797a 2/2: fixup! org-babel-common-header-args-w-values: Add docstring

[ELPA Syncer]

branch: externals/org
commit 080710797ad25e76c4556d2b03cc0aa5313cd187
Author: Ihor Radchenko <yantar92@posteo.net>
Commit: Ihor Radchenko <yantar92@posteo.net>

    fixup! org-babel-common-header-args-w-values: Add docstring
---
 lisp/ob-core.el | 48 ++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 38 insertions(+), 10 deletions(-)

diff --git a/lisp/ob-core.el b/lisp/ob-core.el
index 03b63419ac..2a71dc302a 100644
--- a/lisp/ob-core.el
+++ b/lisp/ob-core.el
@@ -436,16 +436,44 @@ then run `org-babel-switch-to-session'."
     (var       . :any)
     (wrap       . :any))
   "Alist defining common header args and their allowed values.
-Keys of the alist are header arg symbols.  Values of the alist are
-either a symbol `:any' or a list of allowed values.  Each element of
-the value list is either symbol `:any', other symbol representing the
-allowed value, or a list of exclusive values.  `:any' implies that any
-value of the header arg is allowed.  Exclusive values override each
-other when multiple values are used in a given header argument.
-
-A good example of exclusive values is in \"results\" header arg where,
-for example, \"file\" and \"table\" values cannot co-exist.  See info
-node `(org)Results of evaluation' for more details.")
+
+Keys of the alist are header arg symbols.
+Values of the alist are either a symbol `:any' or a list of allowed
+values as symbols:
+
+   (header-name . :any)
+   (header-name . ((value1 value2 value3 ...))
+   (header-name . ((value1 value2 value3 ... :any))
+
+When Org considers header-arg property inheritance, the innermost
+value from the list is considered.
+
+Symbol `:any' in the value list implies that any value is allowed.
+Yet the explicitly listed values from the list will be offered as
+completion candidates.
+
+FIXME: This is currently just supported for `results' and `exports'.
+Values in the alist can also be a list of lists.  The inner lists
+define exclusive groups of values that can be set at the same time for
+a given header argument.
+
+  (results . ((file list ...)
+             (raw html ...))
+
+The above example allows multi-component header arguments like
+
+   #+begin_src bash :results file raw
+   <:results will combine the two values \"file raw\".>
+
+   #+begin_src bash :results file list
+   <:results will only use the last value \"list\".>
+
+   #+property: header-args :results file html
+   ...
+   #+begin_src bash :results list
+   <:results will inherit with partial override \"list html\".>
+
+See info node `(org)Results of evaluation' for more details.")
 
 (defconst org-babel-header-arg-names
   (mapcar #'car org-babel-common-header-args-w-values)