BIND 10 trac449, updated. 42e9021df5556117697f9228645a4ff3eee246ae [trac449] Update doxygen parameters and descriptions
BIND 10 source code commits
bind10-changes at lists.isc.org
Thu Feb 10 09:21:19 UTC 2011
The branch, trac449 has been updated
via 42e9021df5556117697f9228645a4ff3eee246ae (commit)
from 26ab69e18bd0417086315c20192b8b93093bf6e3 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit 42e9021df5556117697f9228645a4ff3eee246ae
Author: Jelte Jansen <jelte at isc.org>
Date: Thu Feb 10 10:19:54 2011 +0100
[trac449] Update doxygen parameters and descriptions
-----------------------------------------------------------------------
Summary of changes:
src/lib/cache/cache_entry_key.h | 14 ++++++++--
src/lib/cache/local_zone_data.h | 14 +++++++---
src/lib/cache/message_entry.h | 45 ++++++++++++++++++++++-----------
src/lib/cache/resolver_cache.h | 53 +++++++++++++++++++++++++++++++++------
src/lib/cache/rrset_cache.h | 16 +++++++++++-
src/lib/cache/rrset_copy.h | 7 +++++
src/lib/cache/rrset_entry.h | 37 +++++++++++++++++---------
7 files changed, 142 insertions(+), 44 deletions(-)
-----------------------------------------------------------------------
diff --git a/src/lib/cache/cache_entry_key.h b/src/lib/cache/cache_entry_key.h
index 0ba0f22..2704b30 100644
--- a/src/lib/cache/cache_entry_key.h
+++ b/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);
diff --git a/src/lib/cache/local_zone_data.h b/src/lib/cache/local_zone_data.h
index 6a4e72c..bcf5a94 100644
--- a/src/lib/cache/local_zone_data.h
+++ b/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:
diff --git a/src/lib/cache/message_entry.h b/src/lib/cache/message_entry.h
index aa32b60..7030dba 100644
--- a/src/lib/cache/message_entry.h
+++ b/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);
//@}
diff --git a/src/lib/cache/resolver_cache.h b/src/lib/cache/resolver_cache.h
index 79c7de8..43e1333 100644
--- a/src/lib/cache/resolver_cache.h
+++ b/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.
diff --git a/src/lib/cache/rrset_cache.h b/src/lib/cache/rrset_cache.h
index ebb3372..d082b3c 100644
--- a/src/lib/cache/rrset_cache.h
+++ b/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:
diff --git a/src/lib/cache/rrset_copy.h b/src/lib/cache/rrset_copy.h
index b4ffcc9..f6bee55 100644
--- a/src/lib/cache/rrset_copy.h
+++ b/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.
diff --git a/src/lib/cache/rrset_entry.h b/src/lib/cache/rrset_entry.h
index 0de62be..f0149a4 100644
--- a/src/lib/cache/rrset_entry.h
+++ b/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_);
}
More information about the bind10-changes
mailing list