FAB-11269 Improve configtx.yaml batch descriptions

The descriptions for the assorted batch size parameters in configtx.yaml
are not as clear as they could be.  This CR expands the descriptions,
including what a batch is, and how it related to transactions and block
sizes.

This makes the issue #Done

Change-Id: If90eb7e902445ba887b8be1508a6247c9ee46cb2
Signed-off-by: Jason Yellick <jyellick@us.ibm.com>

Author: Jason Yellick

sampleconfig/configtx.yaml

@@ -233,22 +233,37 @@ Orderer: &OrdererDefaults
     BatchTimeout: 2s
 
     # Batch Size: Controls the number of messages batched into a block.
+    # The orderer views messages opaquely, but typically, messages may
+    # be considered to be Fabric transactions.  The 'batch' is the group
+    # of messages in the 'data' field of the block.  Blocks will be a few kb
+    # larger than the batch size, when signatures, hashes, and other metadata
+    # is applied.
     BatchSize:
 
         # Max Message Count: The maximum number of messages to permit in a
-        # batch.
+        # batch.  No block will contain more than this number of messages.
         MaxMessageCount: 10
 
         # Absolute Max Bytes: The absolute maximum number of bytes allowed for
-        # the serialized messages in a batch. If the "kafka" OrdererType is
+        # the serialized messages in a batch. The maximum block size is this value
+        # plus the size of the associated metadata (usually a few KB depending
+        # upon the size of the signing identities). Any transaction larger than
+        # this value will be rejected by ordering. If the "kafka" OrdererType is
         # selected, set 'message.max.bytes' and 'replica.fetch.max.bytes' on
         # the Kafka brokers to a value that is larger than this one.
         AbsoluteMaxBytes: 10 MB
 
         # Preferred Max Bytes: The preferred maximum number of bytes allowed
-        # for the serialized messages in a batch. A message larger than the
-        # preferred max bytes will result in a batch larger than preferred max
-        # bytes.
+        # for the serialized messages in a batch. Roughly, this field may be considered
+        # the best effort maximum size of a batch. A batch will fill with messages
+        # until this size is reached (or the max message count, or batch timeout is
+        # exceeded).  If adding a new message to the batch would cause the batch to
+        # exceed the preferred max bytes, then the current batch is closed and written
+        # to a block, and a new batch containing the new message is created.  If a
+        # message larger than the preferred max bytes is received, then its batch
+        # will contain only that message.  Because messages may be larger than
+        # preferred max bytes (up to AbsoluteMaxBytes), some batches may exceed
+        # the preferred max bytes, but will always contain exactly one transaction.
         PreferredMaxBytes: 512 KB
 
     # Max Channels is the maximum number of channels to allow on the ordering