[lldb][doc] Document how our LLDB table gen initialized options

[teemperor]

Summary

This patch adds documentation that should make it easier to migrate from using the old initializers to the table gen format.

[jingham]

Thanks for writing this up!

lldb/trunk/source/Commands/OptionsBase.td

+
+// The fields below describe how the fields of `OptionDefinition` struct are
+// initialized by different definitions in the Options.td and this file.
+////////////////////////////////////////////////////////////////////////////////
+// Field: usage_mask
+// Default value: LLDB_OPT_SET_ALL (Option allowed in all groups)
+// Set by:
+//  - `Group`: Sets a single group to this option.
+//             Example: def foo : Option<"foo", "f">, Group<1>;
+//  - `Groups`: Sets a given list of group numbers.
+//              Example: def foo : Option<"foo", "f">, Groups<[1,4,6]>;
+//  - `GroupRange`: Sets an interval of groups. Start and end are inclusive.
+//                  Example: def foo : Option<"foo", "f">, GroupRange<1, 4>;
+//                           Sets group 1, 2, 3, 4 for the option.
+////////////////////////////////////////////////////////////////////////////////
+// Field: required
+// Default value: false (Not required)
+// Set by:
+//   - `Required`: Marks the option as required.
+//              Example: def foo : Option<"foo", "f">, Required;
+////////////////////////////////////////////////////////////////////////////////
+// Field: long_option
+// Default value: not available (has to be defined in Option)
+// Set by:
+//   - `Option` constructor: Already set by constructor.
+//                           Example: def foo : Option<"long-option", "l">
+//                                                           ^
+//                                                    long option value
+////////////////////////////////////////////////////////////////////////////////
+// Field: short_option
+// Default value: not available (has to be defined in Option)
+// Set by:
+//   - `Option` constructor: Already set by constructor.
+//                           Example: def foo : Option<"long-option", "l">
+//                                                                     ^
+//                                                                short option
+////////////////////////////////////////////////////////////////////////////////
+// Field: option_has_arg
+// Default value: OptionParser::eNoArgument (No argument allowed)
+// Set by:
+//  - `OptionalArg`: Sets the argument type and marks it as optional.
+//  - `Arg`: Sets the argument type and marks it as required.
+//  - `EnumArg`: Sets the argument type to an enum and marks it as required.
+// See argument_type field for more info.
+////////////////////////////////////////////////////////////////////////////////
+// Field: validator
+// Default value: 0 (No validator for option)
+// Set by: Nothing. This is currently only set after initialization in LLDB.
+////////////////////////////////////////////////////////////////////////////////
+// Field: enum_values
+// Default value: {} (No enum associated with this option)
+// Set by:
+//  - `EnumArg`: Sets the argument type and assigns it a enum holding the valid
+//               values. The enum needs to be a variable in the including code.
+//               Marks the option as required (see option_has_arg).
+//               Example: def foo : Option<"foo", "f">,
+//                          EnumArg<"SortOrder",
+//                          "OptionEnumValues(g_sort_option_enumeration)">;
+////////////////////////////////////////////////////////////////////////////////
+// Field: completion_type
+// Default value: CommandCompletions::eNoCompletion (no tab completion)
+// Set by:
+//  - `Completion`: Gives the option a single completion kind.
+//                  Example: def foo : Option<"foo", "f">,
+//                             Completion<"DiskFile">;
+//                           Sets the completion to eDiskFileCompletion
+//
+//  - `Completions`: Sets a given kinds of completions.
+//                   Example: def foo : Option<"foo", "f">,
+//                              Completions<["DiskFile", "DiskDirectory"]>;
+//                            Sets the completion to
+//                            `eDiskFileCompletion | eDiskDirectoryCompletion`.
+////////////////////////////////////////////////////////////////////////////////
+// Field: argument_type
+// Default value: eArgTypeNone
+// Set by:
+//  - `OptionalArg`: Sets the argument type and marks it as optional.
+//                   Example: def foo : Option<"foo", "f">, OptionalArg<"Pid">;
+//                   Sets the argument type to eArgTypePid and marks option as
+//                   optional (see option_has_arg).
+//  - `Arg`: Sets the argument type and marks it as required.
+//           Example: def foo : Option<"foo", "f">, Arg<"Pid">;
+//                    Sets the argument type to eArgTypePid and marks option as
+//                    required (see option_has_arg).
+//  - `EnumArg`: Sets the argument type and assigns it a enum holding the valid
+//               values. The enum needs to be a variable in the including code.
+//               Marks the option as required (see option_has_arg).
+//               Example: def foo : Option<"foo", "f">,
+//                          EnumArg<"SortOrder",
+//                          "OptionEnumValues(g_sort_option_enumeration)">;
+////////////////////////////////////////////////////////////////////////////////
+// Field: usage_text
+// Default value: ""
+// Set by:
+//  - `Desc`: Sets the description for the given option.
+//            Example: def foo : Option<"foo", "f">, Desc<"does nothing.">;
+//                     Sets the description to "does nothing.".
+
 // Base class for all options.
 class Option<string fullname, string shortname> {
   string FullName = fullname;
   string ShortName = shortname;
   // The full associated command/subcommand such as "settings set".
   string Command;
 }