[trac449] Update doxygen parameters and descriptions

src/lib/cache/cache_entry_key.h

@@ -25,12 +25,18 @@ namespace isc {
 namespace cache {
 
 /// \brief Entry Name Generation Functions
+///
 /// Generate the name for message/rrset entries.
-/// The name is name(name of rrset, for message entry,
-/// the name is query name) + str(type)
-/// Note. the name is text string, not wire format.
+///
+/// Concatenates the string representation of the Name and the
+/// string representation of the type number.
+///
+/// Note: the returned name is a text string, not wire format.
 /// eg. if name is 'example.com.', type is 'A', the return
 /// value is 'example.com.1'
+///
+/// \param name The Name to create a text entry for
+/// \param type The RRType to create a text entry for
 /// \return return the entry name.
 const std::string
 genCacheEntryName(const isc::dns::Name& name,
@@ -39,6 +45,8 @@ genCacheEntryName(const isc::dns::Name& name,
 ///
 /// \overload
 ///
+/// \param namestr A string representation of a DNS Name
+/// \param type The value of a DNS RRType
 const std::string
 genCacheEntryName(const std::string& namestr, const uint16_t type);
 

src/lib/cache/local_zone_data.h

@@ -35,14 +35,20 @@ public:
     {}
 
     /// \brief Look up one rrset.
-    /// \return return the shared_ptr of rrset if it can
+    ///
+    /// \param qname The query name to look up
+    /// \param qtype The query type to look up
+    /// \return return the shared_ptr of rrset if it is
     /// found in the local zone, or else, return NULL.
     isc::dns::RRsetPtr lookup(const isc::dns::Name& qname,
                               const isc::dns::RRType& qtype);
 
-    /// \brief Update the rrset in the local zone. If the
-    /// the rrset doesn't exist, it will be added directly,
-    /// or else, the existed one will be overwrited.
+    /// \brief Update the rrset in the local zone.
+    ///
+    /// If the rrset doesn't exist, it will be added.
+    /// Otherwise, the existed one will be overwritten.
+    ///
+    /// \param rrset The rrset to update
     void update(const isc::dns::RRset& rrset);
 
 private:

src/lib/cache/message_entry.h

@@ -34,9 +34,14 @@ class RRsetEntry;
 class RRsetCache;
 
 /// \brief Information to refer an RRset.
-/// There is no class information here, since the rrsets
-/// are cached in the class-specific rrset cache.
+///
+/// There is no class information here, since the rrsets are cached in
+/// the class-specific rrset cache.
 struct RRsetRef{
+    /// \brief Constructor
+    ///
+    /// \param name The Name for the RRset
+    /// \param type the RRType for the RRrset
     RRsetRef(const isc::dns::Name& name, const isc::dns::RRType& type):
             name_(name), type_(type)
     {}
@@ -46,6 +51,7 @@ struct RRsetRef{
 };
 
 /// \brief Message Entry
+///
 /// The object of MessageEntry represents one response message
 /// answered to the resolver client.
 class MessageEntry : public NsasEntry<MessageEntry>,
@@ -54,7 +60,7 @@ class MessageEntry : public NsasEntry<MessageEntry>,
 public:
 
     /// \brief Initialize the message entry object with one dns
-    /// message.
+    ///        message.
     /// \param message The message used to initialize MessageEntry.
     /// \param rrset_cache the pointer of RRsetCache. When one message
     ///        entry is created, rrset cache needs to be updated,
@@ -72,11 +78,12 @@ public:
     ///        as "expire_time - time_now" (expire_time is the
     ///        expiration time of the rrset).
     /// \return return true if the response message can be generated
-    /// from the cached information, or else, return false.
+    ///         from the cached information, or else, return false.
     bool genMessage(const time_t& time_now,
                     isc::dns::Message& response);
 
     /// \brief Get the hash key of the message entry.
+    ///
     /// \return return hash key
     virtual HashKey hashKey() const {
         return (*hash_key_ptr_);
@@ -84,24 +91,29 @@ public:
 
 protected:
     /// \brief Initialize the message entry with dns message.
+    ///
+    /// \param message The Message to initialize the entry with
     void initMessageEntry(const isc::dns::Message& message);
 
     /// \brief These two functions should be static functions
     ///        placed in cc file. Put them here just for easy unit
-    ///        test.
+    ///        tests.
     //@{
     /// \brief Parse the rrsets in specified section.
+    ///
+    /// \param msg The message to parse the RRsets from
+    /// \param section The Section to parse the RRsets from
     /// \param smaller_ttl Get the smallest ttl of rrsets in
     ///        specified section, if it's smaller than the given value.
     /// \param rrset_count the rrset count of the section.
     ///        (TODO for Message, getRRsetCount() should be one
-    //         interface provided by Message.)
+    ///        interface provided by Message.)
     void parseSection(const isc::dns::Message& msg,
-                    const isc::dns::Message::Section& section,
-                    uint32_t& smaller_ttl,
-                    uint16_t& rrset_count);
+                      const isc::dns::Message::Section& section,
+                      uint32_t& smaller_ttl,
+                      uint16_t& rrset_count);
 
-    /// \brief Get RRset Trust worthiness
+    /// \brief Get RRset Trustworthiness
     ///        The algorithm refers to RFC2181 section 5.4.1
     ///        Only the rrset can be updated by the rrsets
     ///        with higher trust level.
@@ -116,21 +128,24 @@ protected:
                                const isc::dns::Message::Section& section);
 
     /// \brief Add rrset to one section of message.
-    /// \param dnssec_need need dnssec records or not.
-    /// \param message The message to add rrsets.
+    ///
+    /// \param message The message to add rrsets to.
     /// \param rrset_entry_vec vector for rrset entries in
     ///        different sections.
+    /// \param section The section to add to
+    /// \param dnssec_need need dnssec records or not.
     void addRRset(isc::dns::Message& message,
                   const std::vector<RRsetEntryPtr> rrset_entry_vec,
                   isc::dns::Message::Section section,
                   bool dnssec_need);
 
     /// \brief Get the all the rrset entries for the message entry.
-    /// \param rrset_entry_vec vector of rrset entries
+    ///
+    /// \param rrset_entry_vec vector to add unexpired rrset entries to
     /// \param time_now the time of now. Used to compare with rrset
     ///        entry's expire time.
-    /// \return return false if any rrset entry has expired, or else,
-    ///         return false.
+    /// \return return false if any rrset entry has expired, true
+    ///         otherwise.
     bool getRRsetEntries(std::vector<RRsetEntryPtr>& rrset_entry_vec,
                          const time_t time_now);
     //@}

src/lib/cache/resolver_cache.h

@@ -39,10 +39,16 @@ typedef std::map<uint16_t, LocalZoneDataPtr> LocalZoneDataMap;
 #define RRSET_CACHE_DEFAULT_SIZE   20000
 
 /// \brief Cache Size Information.
+///
 /// Used to initialize the size of class-specific rrset/message cache.
 struct CacheSizeInfo
 {
-public:    
+public:
+    /// \brief Constructor
+    ///
+    /// \param cls The RRClass code
+    /// \param msg_cache_size The size for the message cache
+    /// \param rst_cache_size The size for the RRset cache
     CacheSizeInfo(uint16_t cls, 
                   uint32_t msg_cache_size,
                   uint32_t rst_cache_size):
@@ -57,6 +63,7 @@ public:
 };
 
 /// \brief  Message has no question section.
+///
 /// Thrown if the given message has no question section when looking up
 /// the message in cache.
 class MessageNoQuestionSection : public isc::Exception {
@@ -66,15 +73,15 @@ public:
     {}
 };
 
-///
 /// \brief Resolver Cache.
+///
 /// The object of ResolverCache represents the cache of the resolver. It may holds
 /// a list of message/rrset cache which are in different class.
-///
 class ResolverCache {
 public:
-    /// \brief Default Construct Function.
-    ///  Only support for class "IN", and message cache size is
+    /// \brief Default Constructor.
+    ///
+    /// Only support for class "IN", and message cache size is
     /// MESSAGE_CACHE_DEFAULT_SIZE, rrset cache size is
     /// RRSET_CACHE_DEFAULT_SIZE
     ResolverCache();
@@ -88,6 +95,9 @@ public:
     //@{
     /// \brief Look up message in cache.
     ///
+    /// \param qname The query name to look up
+    /// \param qtype The query type to look up
+    /// \param qclass The query class to look up
     /// \param response the query message (must in RENDER mode)
     ///        which has question section already(exception
     ///        MessageNoQeustionSection) will be thrown if it has
@@ -102,6 +112,11 @@ public:
                 isc::dns::Message& response) const;
 
     /// \brief Look up rrset in cache.
+    ///
+    /// \param qname The query name to look up
+    /// \param qtype The query type to look up
+    /// \param qclass The query class to look up
+    ///
     /// \return return the shared_ptr of rrset if it can be found,
     ///         or else, return NULL. When looking up, local zone
     ///         data will be searched first, if not found, then
@@ -114,6 +129,11 @@ public:
                               const isc::dns::RRClass& qclass) const;
 
     /// \brief Look up closest rrset in cache.
+    ///
+    /// \param qname The query name to look up
+    /// \param qtype The query type to look up
+    /// \param qclass The query class to look up
+    ///
     /// \return return the shared_ptr of rrset if it can be found in
     ///         cache, or else return NULL.
     ///
@@ -134,6 +154,9 @@ public:
     //@}
 
     /// \brief Update the message in the cache with the new one.
+    ///
+    /// \param msg The message to update
+    ///
     /// \return return true if the message is updated successfully,
     ///         or else, return false.
     ///
@@ -142,9 +165,13 @@ public:
     bool update(const isc::dns::Message& msg);
 
     /// \brief Update the rrset in the cache with the new one.
-    ///        local zone data and rrset cache will be updated together.
-    ///        If the rrset doesn't exist in both of them, then the rrset
-    ///        will be added into both of them.
+    ///
+    /// local zone data and rrset cache will be updated together.
+    /// If the rrset doesn't exist in both of them, then the rrset
+    /// will be added into both of them.
+    ///
+    /// \param rrset_ptr The RRset to update
+    ///
     /// \return return false, if the class of the parameter rrset is
     ///        allowed to be cached.
     ///
@@ -159,16 +186,26 @@ public:
     /// \name Cache Serialization
     //@{
     /// \brief Dump the cache content to one file.
+    ///
+    /// \param file_name file to write to
+    ///
     /// \todo It should can be dumped to one configured database.
     void dump(const std::string& file_name);
 
     /// \brief Load the cache from one file.
+    ///
+    /// \param file to load from
+    ///
     /// \todo It should can be loaded from one configured database.
     void load(const std::string& file_name);
     //@}
 
 protected:
     /// \brief Update rrset cache.
+    ///
+    /// \param rrset_ptr The rrset to update with
+    /// \param rrset_cache_ptr the rrset cache to update
+    ///
     /// \return return true if the rrset is updated in the rrset cache,
     ///         or else return false if failed.
     /// \param rrset_cache_ptr The rrset cache need to be updated.

src/lib/cache/rrset_cache.h

@@ -42,6 +42,8 @@ private:
     RRsetCache(const RRsetCache&);
     RRsetCache& operator=(const RRsetCache&);
 public:
+    /// \brief Constructor
+    ///
     /// \param cache_size the size of rrset cache.
     /// \param rrset_class the class of rrset cache.
     RRsetCache(uint32_t cache_size, uint16_t rrset_class);
@@ -49,7 +51,10 @@ public:
     //@}
 
     /// \brief Look up rrset in cache.
-    /// \return return the shared_ptr of rrset entry if it can
+    ///
+    /// \param qname The query name to look up
+    /// \param qtype The query type 
+    /// \return return the shared_ptr of rrset entry if it can be
     /// found in the cache, or else, return NULL.
     RRsetEntryPtr lookup(const isc::dns::Name& qname,
                          const isc::dns::RRType& qtype);
@@ -68,14 +73,23 @@ public:
                          const RRsetTrustLevel& level);
 
     /// \brief Dump the rrset cache to specified file.
+    ///
+    /// \param file_name The file to write to
+    ///
     /// \todo It should can be dumped to one configured database.
     void dump(const std::string& file_name);
 
     /// \brief Load the cache from one file.
+    ///
+    /// \param file_name The file to read from
+    ///
     /// \todo It should can be loaded from one configured database.
     void load(const std::string& file_name);
 
     /// \brief Resize the size of rrset cache in runtime.
+    ///
+    /// \param The size to resize to
+    /// \return true
     bool resize(uint32_t size);
 
 private:

src/lib/cache/rrset_copy.h

@@ -23,6 +23,13 @@ namespace isc {
 namespace cache {
 
 /// \brief RRset Copy Function
+///
+/// Adds all Rdatas and the RRsig in the source RRset to the target
+/// RRset
+///
+/// \param src RRset to copy from
+/// \param dst RRset to copy to
+///
 /// \note RRset class doesn't provide the interface for
 ///       doing RRset copy. But in cache's code, sometime
 ///       we have to do the copy.

src/lib/cache/rrset_entry.h

@@ -34,27 +34,27 @@ namespace cache {
 /// RFC2181 section5.4.1.
 /// Bigger value is more trustworthy.
 enum RRsetTrustLevel {
-    // Default trust for RRset.
+    /// Default trust for RRset.
     RRSET_TRUST_DEFAULT = 0,
-    // Additional information from non-authoritative answer.
+    /// Additional information from non-authoritative answer.
     RRSET_TRUST_ADDITIONAL_NONAA,
-    // Data from the authority section of a non-authoritative answer
+    /// Data from the authority section of a non-authoritative answer
     RRSET_TRUST_AUTHORITY_NONAA,
-    // Additional information from an authoritative answer.
+    /// Additional information from an authoritative answer.
     RRSET_TRUST_ADDITIONAL_AA,
-    // Non-authoritative data from the answer section of authoritative
-    // answers
+    /// Non-authoritative data from the answer section of authoritative
+    /// answers
     RRSET_TRUST_NONAUTH_ANSWER_AA,
-    // Data from the answer section of a non-authoritative answer.
+    /// Data from the answer section of a non-authoritative answer.
     RRSET_TRUST_ANSWER_NONAA,
-    // Glue from a primary zone, or glue from a zone transfer.
+    /// Glue from a primary zone, or glue from a zone transfer.
     RRSET_TRUST_PRIM_GLUE,
-    // Data from the authority section of an authoritative answer.
+    /// Data from the authority section of an authoritative answer.
     RRSET_TRUST_AUTHORITY_AA,
-    // Authoritative data included in the answer section of
-    // an authoritative reply.
+    /// Authoritative data included in the answer section of
+    /// an authoritative reply.
     RRSET_TRUST_ANSWER_AA,
-    // Data from a primary zone file, other than glue data.
+    /// Data from a primary zone file, other than glue data.
     RRSET_TRUST_PRIM_ZONE_NONGLUE
 };
 
@@ -84,24 +84,35 @@ public:
     //@}
 
     /// \brief Return a pointer to a generated RRset
+    ///
+    /// \return Pointer to the generated RRset
     isc::dns::RRsetPtr getRRset();
 
     /// \brief Get the expiration time of the RRset.
+    ///
+    /// \return The expiration time of the RRset
+    ///
     /// \todo RRsig expiration processing
     time_t getExpireTime() const;
 
     /// \brief Get the ttl of the RRset.
+    ///
+    /// \return The TTL of the RRset
     uint32_t getTTL() {
         updateTTL();
         return (rrset_->getTTL().getValue());
     }
 
+    /// \brief Get the hash key
+    ///
     /// \return return hash key
-    HashKey hashKey() const{
+    HashKey hashKey() const {
         return (hash_key_);
     }
 
     /// \brief get RRset trustworthiness
+    ///
+    /// \return return the trust level
     RRsetTrustLevel getTrustLevel() const {
         return (trust_level_);
     }