Add details about producing tableMetaData via @QMetaDataProducingEntity and customizers

docs/metaData/MetaDataProduction.adoc

@@ -288,33 +288,49 @@ all of the fields in you table in two places (the entity and the table meta-data
 If you are using `QRecordEntity` classes that correspond to your tables, then you can take advantage of some
 additional annotations on those classes, to produce more related meta-data objects associated with those tables.
 The point of this is to eliminate boilerplate, and simplify / speed up the process of getting a new table
-built and deployed in your application, with some bells and whistles added.
+built and deployed in your application.
+
+Furthermore, the case can be made that it is beneficial to keep the meta-data definition for a table as close
+as possible to the entity that corresponds to the table.  This enables modifications to the table (e.g., adding
+a new field/column) to only require edits in one java source file, rather than necessarily requiring edits
+in two files.
 
 === @QMetaDataProducingEntity
-This is an annotation to go on a QRecordEntity class, which you would like to be
+This is an annotation meant to be placed on a `QRecordEntity` subclass, which you would like to be
-processed by `MetaDataProducerHelper`, to automatically produce some meta-data
+processed by an invocation of `MetaDataProducerHelper`, to automatically produce some meta-data
-objects.  Specifically supports:
+objects.
 
-* Making a possible-value-source out of the table.
+This annotation supports:
+
+* Creating table meta-data for the corresponding record entity table. Enabled by setting `produceTableMetaData=true`.
+** One may customize the table meta data that is produced automatically by supplying a class that extends
+`MetaDataCustomizerInterface` in the annotation attribute `tableMetaDataCustomizer`.
+** In addition to (or as an alternative to) the per-table `MetaDataCustomizerInterface` that can be specified
+in `@QMetaDataProducingEntity.tableMetaDataCustomzier`, when an application calls
+`MetaDataProducerHelper.processAllMetaDataProducersInPackage`, an additional `MetaDataCustomizerInterface` can be
+given, to apply a common set of adjustments to all tales being generated by the call.
+* Making a possible-value-source out of the table.  Enabled by setting `producePossibleValueSource=true`.
 * Processing child tables to create joins and childRecordList widgets
 
 === @ChildTable
 This is an annotation used as a value that goes inside a `@QMetadataProducingEntity` annotation, to define
 child-tables, e.g., for producing joins and childRecordList widgets related to the table defined in the entity class.
 
-=== @ChildJoin
+==== @ChildJoin
 This is an annotation used as a value inside a `@ChildTable` inside a `@QMetadataProducingEntity` annotation,
 to control the generation of a `QJoinMetaData`, as a `ONE_TO_MANY` type join from the table represented by
 the annotated entity, to the table referenced in the `@ChildTable` annotation.
 
-=== @ChildRecordListWidget
+==== @ChildRecordListWidget
 This is an annotation used as a value that goes inside a `@QMetadataProducingEntity` annotation, to control
 the generation of a QWidgetMetaData - for a ChildRecordList widget.
 
 [source,java]
-.QRecordEntity with meta-data producing annotations
+.QRecordEntity with meta-data producing annotations and a table MetaDataCustomizer
 ----
 @QMetaDataProducingEntity(
+   produceTableMetaData = true,
+   tableMetaDataCustomizer = MyTable.TableMetaDataCustomizer.class,
    producePossibleValueSource = true,
    childTables = {
       @ChildTable(
@@ -326,13 +342,47 @@ the generation of a QWidgetMetaData - for a ChildRecordList widget.
 public class MyTable extends QRecordEntity
 {
    public static final String TABLE_NAME = "myTable";
-   // class body left as exercise for reader
+
+   public static class TableMetaDataCustomizer implements MetaDataCustomizerInterface<QTableMetaData>
+   {
+      @Override
+      public QTableMetaData customizeMetaData(QInstance qInstance, QTableMetaData table) throws QException
+      {
+         String childJoinName = QJoinMetaData.makeInferredJoinName(TABLE_NAME, MyChildTable.TABLE_NAME);
+
+         table
+            .withUniqueKey(new UniqueKey("name"))
+            .withIcon(new QIcon().withName("table_bar"))
+            .withRecordLabelFormat("%s")
+            .withRecordLabelFields("name")
+
+            .withSection(new QFieldSection("identity", new QIcon().withName("badge"), Tier.T1,
+               List.of("id", "name")))
+            // todo additional sections for other fields
+            .withSection(new QFieldSection("children", new QIcon().withName("account_tree"), Tier.T2)
+               .withWidgetName(childJoinName))
+
+            .withExposedJoin(new ExposedJoin()
+               .withLabel("Children")
+               .withJoinPath(List.of(childJoinName))
+               .withJoinTable(MyChildTable.TABLE_NAME));
+
+         return (table);
+      }
+   }
+
+   @QField(isEditable = false, isPrimaryKey = true)
+   private Integer id;
+
+   // remaining fields, constructors, getters & setters left as an exercise for the reader and/or the IDE
 }
 ----
 
 The class given in the example above, if processed by the `MetaDataProducerHelper`, would add the following
 meta-data objects to your `QInstance`:
 
+* A `QTableMetaData` named `myTable`, with all fields annotated as `@QField` from the `QRecordEntity` class,
+and with additional attributes as set in the `TableMetaDataCustomizer` inner class.
 * A `QPossibleValueSource` named `myTable`, of type `TABLE`, with `myTable` as its backing table.
 * A `QJoinMetaData` named `myTableJoinMyChildTable`, as a `ONE_TO_MANY` type, between those two tables.
 * A `QWidgetMetaData` named `myTableJoinMyChildTable`, as a `CHILD_RECORD_LIST` type, that will show a list of