[PATCH 8/8] Document components.py

[Tom Tromey <tom@tromey.com>]

This adds a comment to document how to update gdbarch.
---
 gdb/components.py | 53 ++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 52 insertions(+), 1 deletion(-)

diff --git a/gdb/components.py b/gdb/components.py
index c854a008a50..36ec45ce531 100644
--- a/gdb/components.py
+++ b/gdb/components.py
@@ -17,7 +17,58 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-
+# How to add to gdbarch:
+#
+# There are four kinds of fields in gdbarch:
+# * Info - you should never need this; it is only for things that
+#          are copied directly from the gdbarch_info.
+# * Value - a variable.
+# * Function - a function pointer.
+# * Method - a function pointer, but the function takes a gdbarch
+#            as its first parameter.
+#
+# You construct a new one with a call to one of those functions.  So,
+# for instance, you can use the function named "Value" to make a new
+# Value.
+#
+# All parameters are keyword-only.  This is done to help catch typos.
+#
+# Some parameters are shared among all types (including Info):
+# * "name" - required, the name of the field.
+# * "return_type" - required, the type of the field.
+#   For functions and methods, this is the return type.
+# * "printer" - an expression to turn this field into a 'const char *'.
+#   This is used for dumping.  The string must live long enough
+#   to be passed to printf.
+#
+# Value, Function, and Method share some more parameters:
+# * "comment" - a comment that's written to the .h file.
+#               Please always use this.  (It isn't currently
+#               a required option for historical reasons.)
+# * "predicate" - a boolean, if True then a _p predicate function
+#               will be generated.
+# * "predefault" - a string (or None, but normally you should leave
+#               it unspecified) that is used to set the field's
+#               initial value.
+# * "postdefault" - a string (or None, but normally you should leave
+#               it unspecified).  If this is specified, and if the
+#               field is invalid after initialization (see "invalid"
+#               to understand this), then the field will be reset to
+#               the "postdefault" value.
+# * "invalid" - a string, or True or False (or None, etc).
+#               If a string, it is an expression to check the
+#               validity of this field.  If False, no validity
+#               checking will be done.  If True, then the default
+#               validity checking will be done -- this means
+#               comparing the value to the "predefault".
+#
+# Function and Method share:
+# * "params" - a tuple of tuples.  Each inner tuple is a pair
+#              of the form (TYPE, NAME), where TYPE is the
+#              type of this argument, and NAME is the name.
+#              Note that while the names could be auto-generated,
+#              this approach lets the "comment" field refer to
+#              arguments in a nicer way.
 
 Info(
     name="bfd_arch_info",
-- 
2.31.1