[clang][cli][docs] Clarify marshalling infrastructure documentation

clang/docs/InternalsManual.rst

@@ -576,11 +576,11 @@ Compiler Invocation
 -------------------
 
 One of the classes provided by the Frontend library is ``CompilerInvocation``,
-which holds information that describe current invocation of the Clang frontend.
-The information typically comes from the command line constructed by the Clang
-driver or from clients performing custom initialization. The data structure is
-split into logical units used by different parts of the compiler, for example
-``PreprocessorOptions``, ``LanguageOptions`` or ``CodeGenOptions``.
+which holds information that describe current invocation of the Clang ``-cc1``
+frontend. The information typically comes from the command line constructed by
+the Clang driver or from clients performing custom initialization. The data
+structure is split into logical units used by different parts of the compiler,
+for example ``PreprocessorOptions``, ``LanguageOptions`` or ``CodeGenOptions``.
 
 Command Line Interface
 ----------------------
@@ -758,12 +758,16 @@ desired.
 Option Marshalling Infrastructure
 ---------------------------------
 
-The option marshalling infrastructure automates the parsing of command line
-arguments into ``CompilerInvocation`` and their generation from
-``CompilerInvocation``. The system replaces lots of repetitive C++ code with
-simple, declarative tablegen annotations and it's being used for the majority of
-the ``-cc1`` command line interface. This section provides an overview of the
-system.
+The option marshalling infrastructure automates the parsing of the Clang
+``-cc1`` frontend command line arguments into ``CompilerInvocation`` and their
+generation from ``CompilerInvocation``. The system replaces lots of repetitive
+C++ code with simple, declarative tablegen annotations and it's being used for
+the majority of the ``-cc1`` command line interface. This section provides an
+overview of the system.
+
+**Note:** The marshalling infrastructure is not intended for driver-only
+options. Only options of the ``-cc1`` frontend need to be marshalled to/from
+``CompilerInvocation`` instance.
 
 To read and modify contents of ``CompilerInvocation``, the marshalling system
 uses key paths, which are declared in two steps. First, a tablegen definition
@@ -856,6 +860,10 @@ generated ``Options.inc``? This is specified by the ``Marshalling`` utilities
 described below. All of them take a key path argument and possibly other
 information required for parsing or generating the command line argument.
 
+**Note:** The marshalling infrastructure is not intended for driver-only
+options. Only options of the ``-cc1`` frontend need to be marshalled to/from
+``CompilerInvocation`` instance.
+
 **Positive Flag**
 
 The key path defaults to ``false`` and is set to ``true`` when the flag is

clang/include/clang/Driver/Options.td

@@ -394,6 +394,8 @@ class MarshalledFlagRec<FlagDefExpanded flag, FlagDefExpanded other,
 // key path via the marshalling infrastructure.
 // Names of the records consist of the specified prefix, "no_" for the negative
 // flag, and NAME.
+// Used for -cc1 frontend options. Driver-only options do not map to
+// CompilerInvocation.
 multiclass BoolOption<string prefix = "", string spelling_base,
                       KeyPathAndMacro kpm, Default default,
                       FlagDef flag1_base, FlagDef flag2_base,
@@ -416,6 +418,8 @@ multiclass BoolOption<string prefix = "", string spelling_base,
 
 /// Creates a BoolOption where both of the flags are prefixed with "f", are in
 /// the Group<f_Group>.
+/// Used for -cc1 frontend options. Driver-only options do not map to
+/// CompilerInvocation.
 multiclass BoolFOption<string flag_base, KeyPathAndMacro kpm,
                        Default default, FlagDef flag1, FlagDef flag2,
                        BothFlags both = BothFlags<[], "">> {
@@ -425,6 +429,8 @@ multiclass BoolFOption<string flag_base, KeyPathAndMacro kpm,
 
 // Creates a BoolOption where both of the flags are prefixed with "g" and have
 // the Group<g_Group>.
+// Used for -cc1 frontend options. Driver-only options do not map to
+// CompilerInvocation.
 multiclass BoolGOption<string flag_base, KeyPathAndMacro kpm,
                        Default default, FlagDef flag1, FlagDef flag2,
                        BothFlags both = BothFlags<[], "">> {

llvm/include/llvm/Option/OptParser.td

@@ -144,56 +144,68 @@ class MetaVarName<string name> { string MetaVarName = name; }
 class Values<string value> { string Values = value; }
 class ValuesCode<code valuecode> { code ValuesCode = valuecode; }
 
-// Helpers for defining marshalling information.
+// Helpers for defining marshalling information (typically used in Clang's -cc1
+// frontend).
 
+// The key path to the mapped field and the macro prefix for the resulting
+// definition database.
 class KeyPathAndMacro<string key_path_prefix, string key_path_base,
                       string macro_prefix = ""> {
   code KeyPath = !strconcat(key_path_prefix, key_path_base);
   code MacroPrefix = macro_prefix;
 }
 
+// Mixin that implies the specified value for the current option when any of the
+// given key paths evaluates to true.
 class ImpliedByAnyOf<list<string> key_paths, code value = "true"> {
   code ImpliedCheck = !foldl("false", key_paths, accumulator, key_path,
                              !strconcat(accumulator, " || ", key_path));
   code ImpliedValue = value;
 }
 
+// Parent class for marshalled options (typically used in Clang's -cc1 frontend).
 class MarshallingInfo<KeyPathAndMacro kpm, code defaultvalue> {
   code KeyPath = kpm.KeyPath;
   code MacroPrefix = kpm.MacroPrefix;
   code DefaultValue = defaultvalue;
 }
 
+// Marshalled option accepting a string argument.
 class MarshallingInfoString<KeyPathAndMacro kpm, code defaultvalue="std::string()">
   : MarshallingInfo<kpm, defaultvalue> {
   code Normalizer = "normalizeString";
   code Denormalizer = "denormalizeString";
 }
 
+// Marshalled option accepting an integer argument.
 class MarshallingInfoInt<KeyPathAndMacro kpm, code defaultvalue="0", code type="unsigned">
   : MarshallingInfo<kpm, defaultvalue> {
   code Normalizer = "normalizeStringIntegral<"#type#">";
   code Denormalizer = "denormalizeString<"#type#">";
 }
 
+// Marshalled option accepting vector of strings.
 class MarshallingInfoStringVector<KeyPathAndMacro kpm>
   : MarshallingInfo<kpm, "std::vector<std::string>({})"> {
   code Normalizer = "normalizeStringVector";
   code Denormalizer = "denormalizeStringVector";
 }
 
+// Marshalled option - single positive flag.
 class MarshallingInfoFlag<KeyPathAndMacro kpm, code defaultvalue = "false">
   : MarshallingInfo<kpm, defaultvalue> {
   code Normalizer = "normalizeSimpleFlag";
   code Denormalizer = "denormalizeSimpleFlag";
 }
 
+// Marshalled option - single negative flag.
 class MarshallingInfoNegativeFlag<KeyPathAndMacro kpm, code defaultvalue = "true">
   : MarshallingInfo<kpm, defaultvalue> {
   code Normalizer = "normalizeSimpleNegativeFlag";
   code Denormalizer = "denormalizeSimpleFlag";
 }
 
+// Marshalled option - single flag contributing to a bitfield.
 class MarshallingInfoBitfieldFlag<KeyPathAndMacro kpm, code value>
   : MarshallingInfoFlag<kpm, "0u"> {
   code Normalizer = "makeFlagToValueNormalizer("#value#")";
@@ -201,7 +213,7 @@ class MarshallingInfoBitfieldFlag<KeyPathAndMacro kpm, code value>
   code ValueExtractor = "(extractMaskValue<unsigned, decltype("#value#"), "#value#">)";
 }
 
-// Marshalling info for booleans. Applied to the flag setting keypath to false.
+// Implementation detail of BoolOption.
 class MarshallingInfoBooleanFlag<KeyPathAndMacro kpm, code defaultvalue, code value, code name,
                                  code other_value, code other_name>
   : MarshallingInfoFlag<kpm, defaultvalue> {
@@ -209,8 +221,8 @@ class MarshallingInfoBooleanFlag<KeyPathAndMacro kpm, code defaultvalue, code va
   code Denormalizer = "makeBooleanOptionDenormalizer("#value#")";
 }
 
-// Marshalling info for enums. Typically used with `Values`, `NormalizedValues`
-// and `NormalizedValuesScope` mixins.
+// Marshalled option accepting any of the specified enum values.
+// Typically used with `Values`, `NormalizedValues` and `NormalizedValuesScope`.
 class MarshallingInfoEnum<KeyPathAndMacro kpm, code defaultvalue>
   : MarshallingInfo<kpm, defaultvalue> {
   code Normalizer = "normalizeSimpleEnum";