[trac741] Message descriptions

src/lib/cache/cache_messages.mes

@@ -14,68 +14,167 @@
 
 $NAMESPACE isc::cache
 
-% CACHE_LOCALZONE_UPDATE updating local zone element at key %1
+% CACHE_ENTRY_MISSING_RRSET missing RRset to generate message for %1
 
-% CACHE_LOCALZONE_UNKNOWN entry with key %1 not found in local zone data
+The cache tried to generate the complete answer message. It knows the structure
+of the message, but some of the RRsets to be put there are not in cache (they
+probably expired already). Therefore it pretends the message was not found.
 
 % CACHE_LOCALZONE_FOUND found entry with key %1 in local zone data
 
-% CACHE_MESSAGES_INIT initialized message cache for %1 %2 messages
+Debug message, noting that the requested data was successfully found in the
+local zone data of the cache.
+
+% CACHE_LOCALZONE_UNKNOWN entry with key %1 not found in local zone data
+
+Debug message. The requested data was not found in the local zone data.
+
+% CACHE_LOCALZONE_UPDATE updating local zone element at key %1
+
+Debug message issued when there's update to the local zone section of cache.
 
 % CACHE_MESSAGES_DEINIT deinitialized message cache
 
-% CACHE_MESSAGES_FOUND found a message entry for %1 in the message cache
+Debug message. It is issued when the server deinitializes the message cache.
 
 % CACHE_MESSAGES_EXPIRED found an expired message entry for %1 in the message cache
 
-% CACHE_MESSAGES_UNKNOWN no entry for %1 found in the message cache
+Debug message. The requested data was found in the message cache, but it
+already expired. Therefore the cache removes the entry and pretends it found
+nothing.
+
+% CACHE_MESSAGES_FOUND found a message entry for %1 in the message cache
+
+Debug message. We found the whole message in the cache, so it can be returned
+to user without any other lookups.
+
+% CACHE_MESSAGES_INIT initialized message cache for %1 %2 messages
+
+Debug message issued when a new message cache is issued. It lists the class
+of messages it can hold and the maximum size of the cache.
+
+% CACHE_MESSAGES_REMOVE removing old instance of %1/%2/%3 first
+
+Debug message. This may follow CACHE_MESSAGES_UPDATE and indicates that, while
+updating, the old instance is being removed prior of inserting a new one.
 
 % CACHE_MESSAGES_UNCACHEABLE not inserting uncacheable message %1/%2/%3
 
+Debug message, noting that the given message can not be cached. This is for
+some reason described in RFC2308.
+
+% CACHE_MESSAGES_UNKNOWN no entry for %1 found in the message cache
+
+Debug message. The message cache didn't find any entry for the given key.
+
 % CACHE_MESSAGES_UPDATE updating message entry %1/%2/%3
 
-% CACHE_MESSAGES_REMOVE removing old instance of %1/%2/%3 first
+Debug message issued when the message cache is being updated with a new
+message. Either the old instance is removed or, if none is found, new one
+is created.
 
-% CACHE_ENTRY_MISSING_RRSET missing RRset to generate message for %1
+% CACHE_RESOLVER_DEEPEST looking up deepest NS for %1/%2
 
-% CACHE_RESOLVER_INIT initializing resolver cache for class %1
+Debug message. The resolver cache is looking up the deepest known nameserver,
+so the resolution doesn't have to start from the root.
 
 % CACHE_RESOLVER_INIT_INFO initializing resolver cache for class %1
 
-% CACHE_RESOLVER_LOOKUP_MSG looking up message in resolver cache for %1/%2
+Debug message, the resolver cache is being created for this given class. The
+difference from CACHE_RESOLVER_INIT is only in different format of passed
+information, otherwise it does the same.
 
-% CACHE_RESOLVER_LOOKUP_RRSET looking up RRset in resolver cache for %1/%2
+% CACHE_RESOLVER_INIT initializing resolver cache for class %1
 
-% CACHE_RESOLVER_NO_QUESTION answer message for %1/%2 has empty question section
+Debug message. The resolver cache is being created for this given class.
 
 % CACHE_RESOLVER_LOCAL_MSG message for %1/%2 found in local zone data
 
+Debug message. The resolver cache found a complete message for the user query
+in the zone data.
+
 % CACHE_RESOLVER_LOCAL_RRSET RRset for %1/%2 found in local zone data
 
-% CACHE_RESOLVER_UPDATE_MSG updating message for %1/%2/%3
+Debug message. The resolver cache found a requested RRset in the local zone
+data.
 
-% CACHE_RESOLVER_UPDATE_RRSET updating RRset for %1/%2/%3
+% CACHE_RESOLVER_LOOKUP_MSG looking up message in resolver cache for %1/%2
+
+Debug message. The resolver cache is trying to find a message to answer the
+user query.
+
+% CACHE_RESOLVER_LOOKUP_RRSET looking up RRset in resolver cache for %1/%2
+
+Debug message. The resolver cache is trying to find an RRset (which usually
+originates as internally from resolver).
+
+% CACHE_RESOLVER_NO_QUESTION answer message for %1/%2 has empty question section
+
+The cache tried to fill in found data into the response message. But it
+discovered the message contains no question section, which is invalid.
+This is likely a programmer error, please submit a bug report.
 
 % CACHE_RESOLVER_UNKNOWN_CLASS_MSG no cache for class %1
 
+Debug message. While trying to lookup a message in the resolver cache, it was
+discovered there's no cache for this class at all. Therefore no message is
+found.
+
 % CACHE_RESOLVER_UNKNOWN_CLASS_RRSET no cache for class %1
 
-% CACHE_RESOLVER_DEEPEST looking up deepest NS for %1/%2
+Debug message. While trying to lookup an RRset in the resolver cache, it was
+discovered there's no cache for this class at all. Therefore no data is found.
+
+% CACHE_RESOLVER_UPDATE_MSG updating message for %1/%2/%3
+
+Debug message. The resolver is updating a message in the cache.
+
+% CACHE_RESOLVER_UPDATE_RRSET updating RRset for %1/%2/%3
+
+Debug message. The resolver is updating an RRset in the cache.
 
 % CACHE_RESOLVER_UPDATE_UNKNOWN_CLASS_MSG no cache for class %1
 
+Debug message. While trying to insert a message into the cache, it was
+discovered that there's no cache for the class of message. Therefore
+the message will not be cached.
+
 % CACHE_RESOLVER_UPDATE_UNKNOWN_CLASS_RRSET no cache for class %1
 
+Debug message. While trying to insert an RRset into the cache, it was
+discovered that there's no cache for the class of the RRset. Therefore
+the message will not be cached.
+
+% CACHE_RRSET_EXPIRED found expired RRset %1/%2
+
+Debug message. There' the data requested in the RRset cache. However, it is
+expired, so the cache removed it and is going to pretend nothing was found.
+
 % CACHE_RRSET_INIT initializing RRset cache for %2 RRsets of class %1
 
+Debug message. The RRset cache to hold at most this many RRsets for the given
+class is being created.
+
 % CACHE_RRSET_LOOKUP looking up %1/%2 in RRset cache
 
-% CACHE_RRSET_EXPIRED found expired RRset %1/%2
+Debug message. The resolver is trying to look up data in the RRset cache.
 
 % CACHE_RRSET_NOT_FOUND no RRset found for %1/%2
 
-% CACHE_RRSET_UPDATE updating RRset %1/%2/%3 in the cache
+Debug message which can follow CACHE_RRSET_LOOKUP. This means the data is not
+in the cache.
+
+% CACHE_RRSET_REMOVE_OLD removing old RRset for %1/%2/%3 to make space for new one
+
+Debug message which can follow CACHE_RRSET_UPDATE. During the update, the cache
+removed an old instance of the RRset to replace it with the new one.
 
 % CACHE_RRSET_UNTRUSTED not replacing old RRset for %1/%2/%3, it has higher trust level
 
-% CACHE_RRSET_REMOVE_OLD removing old RRset for %1/%2/%3 to make space for new one
+Debug message which can follow CACHE_RRSET_UPDATE. The cache already holds the
+same RRset, but from more trusted source, so the old one is kept and new one
+ignored.
+
+% CACHE_RRSET_UPDATE updating RRset %1/%2/%3 in the cache
+
+Debug message. The RRset is updating its data with this giver RRset.