[trac1078] Update message descriptions in line with comments in ticket

src/bin/resolver/resolver_messages.mes

@@ -16,151 +16,174 @@
 # along with the resolver methods.
 
 % RESOLVER_AXFR_TCP AXFR request received over TCP
-A debug message, the resolver received a NOTIFY message over TCP.  The server
+This is a debug message output when the resolver received a request for
-cannot process it and will return an error message to the sender with the
+an AXFR (full transfer of a zone) over TCP.  Only authoritative servers
-RCODE set to NOTIMP.
+are able to handle AXFR requests, so the resolver will return an error
+message to the sender with the RCODE set to NOTIMP.
 
 % RESOLVER_AXFR_UDP AXFR request received over UDP
-A debug message, the resolver received a NOTIFY message over UDP.  The server
+This is a debug message output when the resolver received a request for
-cannot process it (and in any case, an AXFR request should be sent over TCP)
+an AXFR (full transfer of a zone) over TCP.  Only authoritative servers
-and will return an error message to the sender with the RCODE set to FORMERR.
+are able to handle AXFR requests (and in any case, an AXFR request should
+be sent over TCP), so the resolver will return an error message to the
+sender with the RCODE set to NOTIMP.
 
 % RESOLVER_CLIENT_TIME_SMALL client timeout of %1 is too small
-An error indicating that the configuration value specified for the query
+During the update of the resolver's configuration parameters, the value
-timeout is too small.
+of the client timeout was found to be too small.  The configuration
+update was abandoned and the parameters were not changed.
 
 % RESOLVER_CONFIG_CHANNEL configuration channel created
-A debug message, output when the resolver has successfully established a
+This is a debug message output when the resolver has successfully
-connection to the configuration channel.
+established a connection to the configuration channel.
 
 % RESOLVER_CONFIG_ERROR error in configuration: %1
-An error was detected in a configuration update received by the resolver. This
+An error was detected in a configuration update received by the
-may be in the format of the configuration message (in which case this is a
+resolver. This may be in the format of the configuration message (in
-programming error) or it may be in the data supplied (in which case it is
+which case this is a programming error) or it may be in the data supplied
-a user error).  The reason for the error, given as a parameter in the message,
+(in which case it is a user error).  The reason for the error, included
-will give more details.
+in the message, will give more details.  The configuration update is
+not applied and the resolver parameters were not changed.
 
 % RESOLVER_CONFIG_LOADED configuration loaded
-A debug message, output when the resolver configuration has been successfully
+This is a debug message output when the resolver configuration has been
-loaded.
+successfully loaded.
 
 % RESOLVER_CONFIG_UPDATED configuration updated: %1
-A debug message, the configuration has been updated with the specified
+This is a debug message output when the resolver configuration is being
-information.
+updated with the specified information.
 
 % RESOLVER_CREATED main resolver object created
-A debug message, output when the Resolver() object has been created.
+This is a debug message indicating that the main resolver object has
+been created.
 
 % RESOLVER_DNS_MESSAGE_RECEIVED DNS message received: %1
-A debug message, this always precedes some other logging message and is the
+This is a debug message from the resolver listing the contents of a
-formatted contents of the DNS packet that the other message refers to.
+received DNS message.
 
 % RESOLVER_DNS_MESSAGE_SENT DNS message of %1 bytes sent: %2
-A debug message, this contains details of the response sent back to the querying
+This is a debug message containing details of the response returned by
-system.
+the resolver to the querying system.
 
 % RESOLVER_FAILED resolver failed, reason: %1
-This is an error message output when an unhandled exception is caught by the
+This is an error message output when an unhandled exception is caught
-resolver.  All it can do is to shut down.
+by the resolver.  After this, the resolver will shut itself down.
+Please submit a bug report.
 
 % RESOLVER_FORWARD_ADDRESS setting forward address %1(%2)
-This message may appear multiple times during startup, and it lists the
+If the resolver is running in forward mode, this message will appear
-forward addresses used by the resolver when running in forwarding mode.
+during startup to list the forward address.  If multiple addresses are
+specified, it will appear once for each address.
 
 % RESOLVER_FORWARD_QUERY processing forward query
-The received query has passed all checks and is being forwarded to upstream
+This is a debug message indicating that a query received by the resolver
+has passed a set of checks (message is well-formed, it is allowed by the
+ACL, it is a supported opcode etc.) and is being forwarded to upstream
 servers.
 
 % RESOLVER_HEADER_ERROR message received, exception when processing header: %1
-A debug message noting that an exception occurred during the processing of
+This is a debug message from the resolver noting that an exception
-a received packet.  The packet has been dropped.
+occurred during the processing of a received packet.  The packet has
+been dropped.
 
 % RESOLVER_IXFR IXFR request received
-The resolver received a NOTIFY message over TCP.  The server cannot process it
+This is a debug message indicating that the resolver received a request
-and will return an error message to the sender with the RCODE set to NOTIMP.
+for an IXFR (incremental transfer of a zone).  Only authoritative servers
+are able to handle IXFR requests, so the resolver will return an error
+message to the sender with the RCODE set to NOTIMP.
 
 % RESOLVER_LOOKUP_TIME_SMALL lookup timeout of %1 is too small
-An error indicating that the configuration value specified for the lookup
+During the update of the resolver's configuration parameters, the value
-timeout is too small.
+of the lookup timeout was found to be too small.  The configuration
+update will not be applied.
 
 % RESOLVER_MESSAGE_ERROR error parsing received message: %1 - returning %2
-A debug message noting that the resolver received a message and the
+This is a debug message noting that parsing of the body of a received
-parsing of the body of the message failed due to some error (although
+message by the resolver failed due to some error (although the parsing of
-the parsing of the header succeeded).  The message parameters give a
+the header succeeded).  The message parameters give a textual description
-textual description of the problem and the RCODE returned.
+of the problem and the RCODE returned.
 
 % RESOLVER_NEGATIVE_RETRIES negative number of retries (%1) specified in the configuration
-An error message indicating that the resolver configuration has specified a
+This error is issued when a resolver configuration update has specified
-negative retry count.  Only zero or positive values are valid.
+a negative retry count: only zero or positive values are valid.  The
+configuration update was abandoned and the parameters were not changed.
 
 % RESOLVER_NON_IN_PACKET non-IN class request received, returning REFUSED message
-A debug message, the resolver has received a DNS packet that was not IN class.
+This debug message is issued when resolver has received a DNS packet that
-The resolver cannot handle such packets, so is returning a REFUSED response to
+was not IN (Internet) class.  The resolver cannot handle such packets,
-the sender.
+so is returning a REFUSED response to the sender.
 
 % RESOLVER_NORMAL_QUERY processing normal query
-The received query has passed all checks and is being processed by the resolver.
+This is a debug message indicating that the query received by the resolver
+has passed a set of checks (message is well-formed, it is allowed by the
+ACL, it is a supported opcode etc.) and is being processed the resolver.
 
 % RESOLVER_NOTIFY_RECEIVED NOTIFY arrived but server is not authoritative
-The resolver received a NOTIFY message.  As the server is not authoritative it
+The resolver has received a NOTIFY message.  As the server is not
-cannot process it, so it returns an error message to the sender with the RCODE
+authoritative it cannot process it, so it returns an error message to
-set to NOTAUTH.
+the sender with the RCODE set to NOTAUTH.
 
 % RESOLVER_NOT_ONE_QUESTION query contained %1 questions, exactly one question was expected
-A debug message, the resolver received a query that contained the number of
+This debug message indicates that the resolver received a query that
-entires in the question section detailed in the message.  This is a malformed
+contained the number of entries in the question section detailed in
-message, as a DNS query must contain only one question.  The resolver will
+the message.  This is a malformed message, as a DNS query must contain
-return a message to the sender with the RCODE set to FORMERR.
+only one question.  The resolver will return a message to the sender
+with the RCODE set to FORMERR.
 
 % RESOLVER_NO_ROOT_ADDRESS no root addresses available
-A warning message during startup, indicates that no root addresses have been
+A warning message issued during resolver startup, this indicates that
-set.  This may be because the resolver will get them from a priming query.
+no root addresses have been set.  This may be because the resolver will
+get them from a priming query.
 
 % RESOLVER_PARSE_ERROR error parsing received message: %1 - returning %2
-A debug message noting that the resolver received a message and the parsing
+This is a debug message noting that the resolver received a message and
-of the body of the message failed due to some non-protocol related reason
+the parsing of the body of the message failed due to some non-protocol
-(although the parsing of the header succeeded).  The message parameters give
+related reason (although the parsing of the header succeeded).
-a textual description of the problem and the RCODE returned.
+The message parameters give a textual description of the problem and
+the RCODE returned.
 
 % RESOLVER_PRINT_COMMAND print message command, arguments are: %1
-This message is logged when a "print_message" command is received over the
+This debug message is logged when a "print_message" command is received
-command channel.
+by the resolver over the command channel.
 
 % RESOLVER_PROTOCOL_ERROR protocol error parsing received message: %1 - returning %2
-A debug message noting that the resolver received a message and the parsing
+This is a debug message noting that the resolver received a message and
-of the body of the message failed due to some protocol error (although the
+the parsing of the body of the message failed due to some protocol error
-parsing of the header succeeded).  The message parameters give a textual
+(although the parsing of the header succeeded).  The message parameters
-description of the problem and the RCODE returned.
+give a textual description of the problem and the RCODE returned.
 
 % RESOLVER_QUERY_SETUP query setup
-A debug message noting that the resolver is creating a RecursiveQuery object.
+This is a debug message noting that the resolver is creating a
+RecursiveQuery object.
 
 % RESOLVER_QUERY_SHUTDOWN query shutdown
-A debug message noting that the resolver is destroying a RecursiveQuery object.
+This is a debug message noting that the resolver is destroying a
+RecursiveQuery object.
 
 % RESOLVER_QUERY_TIME_SMALL query timeout of %1 is too small
-An error indicating that the configuration value specified for the query
+During the update of the resolver's configuration parameters, the value
-timeout is too small.
+of the query timeout was found to be too small.  The configuration
+parameters were not changed.
 
 % RESOLVER_RECEIVED_MESSAGE resolver has received a DNS message
-A debug message indicating that the resolver has received a message.  Depending
+This is a debug message indicating that the resolver has received a
-on the debug settings, subsequent log output will indicate the nature of the
+DNS message.  Depending on the debug settings, subsequent log output
-message.
+will indicate the nature of the message.
 
 % RESOLVER_RECURSIVE running in recursive mode
-This is an informational message that appears at startup noting that the
+This is an informational message that appears at startup noting that
-resolver is running in recursive mode.
+the resolver is running in recursive mode.
 
 % RESOLVER_SERVICE_CREATED service object created
-A debug message, output when the main service object (which handles the
+This debug message is output when resolver creates the main service object
-received queries) is created.
+(which handles the received queries).
 
 % RESOLVER_SET_PARAMS query timeout: %1, client timeout: %2, lookup timeout: %3, retry count: %4
-A debug message, lists the parameters being set for the resolver.  These are:
+This debug message lists the parameters being set for the resolver.  These are:
 query timeout: the timeout (in ms) used for queries originated by the resolver
-to upstream servers.  Client timeout: the interval to resolver a query by
+to upstream servers.  Client timeout: the interval to resolve a query by
 a client: after this time, the resolver sends back a SERVFAIL to the client
-whilst continuing to resolver the query. Lookup timeout: the time at which the
+whilst continuing to resolve the query. Lookup timeout: the time at which the
 resolver gives up trying to resolve a query.  Retry count: the number of times
 the resolver will retry a query to an upstream server if it gets a timeout.
 
@@ -169,17 +192,18 @@ resolution of the client query might require a large number of queries to
 upstream nameservers.  Even if none of these queries timeout, the total time
 taken to perform all the queries may exceed the client timeout.  When this
 happens, a SERVFAIL is returned to the client, but the resolver continues
-with the resolution process. Data received is added to the cache.  However,
+with the resolution process; data received is added to the cache.  However,
 there comes a time - the lookup timeout - when even the resolver gives up.
 At this point it will wait for pending upstream queries to complete or
 timeout and drop the query.
 
 % RESOLVER_SET_ROOT_ADDRESS setting root address %1(%2)
-This message may appear multiple times during startup; it lists the root
+This message gives the address of one of the root servers used by the
-addresses used by the resolver.
+resolver.  It is output during startup and may appear multiple times,
+oncee for each root server address.
 
 % RESOLVER_SHUTDOWN resolver shutdown complete
-This information message is output when the resolver has shut down.
+This informational message is output when the resolver has shut down.
 
 % RESOLVER_STARTED resolver started
 This informational message is output by the resolver when all initialization
@@ -189,35 +213,36 @@ has been completed and it is entering its main loop.
 An informational message, this is output when the resolver starts up.
 
 % RESOLVER_UNEXPECTED_RESPONSE received unexpected response, ignoring
-A debug message noting that the server has received a response instead of a
+This is a debug message noting that the resolver received a DNS response
-query and is ignoring it.
+packet on the port on which is it listening for queries.  The packet
+has been ignored.
 
 % RESOLVER_UNSUPPORTED_OPCODE opcode %1 not supported by the resolver
-A debug message, the resolver received a message with an unsupported opcode
+This is debug message output when the resolver received a message with an
-(it can only process QUERY opcodes).  It will return a message to the sender
+unsupported opcode (it can only process QUERY opcodes).  It will return
-with the RCODE set to NOTIMP.
+a message to the sender with the RCODE set to NOTIMP.
-
+
-% RESOLVER_SET_QUERY_ACL   query ACL is configured
+% RESOLVER_SET_QUERY_ACL query ACL is configured
-A debug message that appears when a new query ACL is configured for the
+This debug message is generated when a new query ACL is configured for
-resolver.
+the resolver.
-
+
-% RESOLVER_QUERY_ACCEPTED   query accepted: '%1/%2/%3' from %4
+% RESOLVER_QUERY_ACCEPTED query accepted: '%1/%2/%3' from %4
-A debug message that indicates an incoming query is accepted in terms of
+This debug message is produced by the resolver when an incoming query
-the query ACL.  The log message shows the query in the form of
+is accepted in terms of the query ACL.  The log message shows the query
-<query name>/<query type>/<query class>, and the client that sends the
+in the form of <query name>/<query type>/<query class>, and the client
-query in the form of <Source IP address>#<source port>.
+that sends the query in the form of <Source IP address>#<source port>.
-
+
-% RESOLVER_QUERY_REJECTED   query rejected: '%1/%2/%3' from %4
+% RESOLVER_QUERY_REJECTED query rejected: '%1/%2/%3' from %4
-An informational message that indicates an incoming query is rejected
+This is an informational message that indicates an incoming query has
-in terms of the query ACL.  This results in a response with an RCODE of
+been rejected by the resolver because of the query ACL.  This results
-REFUSED. The log message shows the query in the form of <query
+in a response with an RCODE of REFUSED. The log message shows the query
-name>/<query type>/<query class>, and the client that sends the
+in the form of <query name>/<query type>/<query class>, and the client
-query in the form of <Source IP address>#<source port>.
+that sends the query in the form of <Source IP address>#<source port>.
-
+
-% RESOLVER_QUERY_DROPPED    query dropped: '%1/%2/%3' from %4
+% RESOLVER_QUERY_DROPPED query dropped: '%1/%2/%3' from %4
-An informational message that indicates an incoming query is dropped
+This is an informational message that indicates an incoming query has
-in terms of the query ACL.  Unlike the RESOLVER_QUERY_REJECTED
+been dropped by the resolver because of the query ACL.  Unlike the
-case, the server does not return any response.  The log message
+RESOLVER_QUERY_REJECTED case, the server does not return any response.
-shows the query in the form of <query name>/<query type>/<query
+The log message shows the query in the form of <query name>/<query
-class>, and the client that sends the query in the form of <Source
+type>/<query class>, and the client that sends the query in the form of
-IP address>#<source port>.
+<Source IP address>#<source port>.

src/lib/resolve/resolve_messages.mes

@@ -123,11 +123,11 @@ called because a nameserver has been found, and that a query is being sent
 to the specified nameserver.
 
 % RESLIB_TEST_SERVER setting test server to %1(%2)
-This is an internal debugging message and is only generated in unit tests.
+This is a warning message only generated in unit tests.  It indicates
-It indicates that all upstream queries from the resolver are being routed to
+that all upstream queries from the resolver are being routed to the
-the specified server, regardless of the address of the nameserver to which
+specified server, regardless of the address of the nameserver to which
-the query would normally be routed.  As it should never be seen in normal
+the query would normally be routed.  If seen during normal operation,
-operation, it is a warning message instead of a debug message.
+please log a bug report.
 
 % RESLIB_TEST_UPSTREAM sending upstream query for <%1> to test server at %2
 This is a debug message and should only be seen in unit tests.  A query for
@@ -135,8 +135,8 @@ the specified <name, class, type> tuple is being sent to a test nameserver
 whose address is given in the message.
 
 % RESLIB_TIMEOUT query <%1> to %2 timed out
-A debug message indicating that the specified query has timed out and as
+A debug message indicating that the specified upstream query has timed out and
-there are no retries left, an error will be reported.
+there are no retries left.
 
 % RESLIB_TIMEOUT_RETRY query <%1> to %2 timed out, re-trying (retries left: %3)
 A debug message indicating that the specified query has timed out and that