Improve message_size_limit and various max_* option docs.

Closes #448.

ChangeLog.txt

@@ -7,6 +7,9 @@ Broker:
 Documentation:
 - Improve details on global/per listener options in the mosquitto.conf man page.
  Closes #274.
+- Clarify behaviour when clients exceed the `message_size_limit`. Closes #448.
+- Improve documentation for `max_inflight_bytes`, `max_inflight_messages`,
+ and `max_queued_messages`.
 
 Build:
 - Fix missing function warnings on NetBSD.

man/mosquitto.conf.5.xml

@@ -551,9 +551,12 @@ log_timestamp_format %Y-%m-%dT%H:%M:%S
  <varlistentry>
  <term><option>max_inflight_bytes</option> <replaceable>count</replaceable></term>
  <listitem>
- <para>QoS 1 and 2 messages will be allowed in flight until this byte
- limit is reached. Defaults to 0. (No limit)
- See also the <option>max_inflight_messages</option> option.</para>
+ <para>Outgoing QoS 1 and 2 messages will be allowed in flight until this byte
+ limit is reached. This allows control of outgoing message rate based on
+ message size rather than message count. If the limit is set to 100,
+ messages of over 100 bytes are still allowed, but only a single message
+ can be in flight at once. Defaults to 0. (No limit).</para>
+ <para>See also the <option>max_inflight_messages</option> option.</para>
 
  <para>This option applies globally.</para>
 
@@ -563,7 +566,7 @@ log_timestamp_format %Y-%m-%dT%H:%M:%S
  <varlistentry>
  <term><option>max_inflight_messages</option> <replaceable>count</replaceable></term>
  <listitem>
- <para>The maximum number of QoS 1 or 2 messages that can be
+ <para>The maximum number of outgoing QoS 1 or 2 messages that can be
  in the process of being transmitted simultaneously.
  This includes messages currently going through
  handshakes and messages that are being retried.
@@ -631,9 +634,12 @@ log_timestamp_format %Y-%m-%dT%H:%M:%S
  <varlistentry>
  <term><option>max_queued_bytes</option> <replaceable>count</replaceable></term>
  <listitem>
- <para>QoS 1 and 2 messages above those currently in-flight will be
- queued (per client) until this limit is exceeded.
- Defaults to 0. (No maximum) See also the
+ <para>The number of outgoing QoS 1 and 2 messages above those currently in-flight will be
+ queued (per client) by the broker. Once this limit has been reached, subsequent
+ messages will be silently dropped. This is an important option if you are sending
+ messages at a high rate and/or have clients who are slow to respond or may be offline
+ for extended periods of time. Defaults to 0. (No maximum).</para>
+ <para>See also the
  <option>max_queued_messages</option> option.
  If both max_queued_messages and max_queued_bytes are specified,
  packets will be queued until the first limit is reached.
@@ -682,8 +688,13 @@ log_timestamp_format %Y-%m-%dT%H:%M:%S
  <listitem>
  <para>This option sets the maximum publish payload size
  that the broker will allow. Received messages that
- exceed this size will not be accepted by the broker.
- The default value is 0, which means that all valid MQTT
+ exceed this size will not be accepted by the broker. This means that the
+ message will not be forwarded on to subscribing clients, but the QoS flow
+ will be completed for QoS 1 or QoS 2 messages. MQTT v5 clients using QoS 1
+ or QoS 2 will receive a PUBACK or PUBREC with the "implementation specific
+ error" reason code.</para>
+
+ <para>The default value is 0, which means that all valid MQTT
  messages are accepted. MQTT imposes a maximum payload
  size of 268435455 bytes.</para>