[svn] commit: r1812 - /branches/trac49/src/lib/dns/name.h

BIND 10 source code commits bind10-changes at lists.isc.org
Wed May 12 04:20:41 UTC 2010


Author: jinmei
Date: Wed May 12 04:20:41 2010
New Revision: 1812

Log:
added documentation

Modified:
    branches/trac49/src/lib/dns/name.h

Modified: branches/trac49/src/lib/dns/name.h
==============================================================================
--- branches/trac49/src/lib/dns/name.h (original)
+++ branches/trac49/src/lib/dns/name.h Wed May 12 04:20:41 2010
@@ -84,7 +84,7 @@
 
 ///
 /// \brief A standard DNS module exception that is thrown if the name parser
-/// finds the input (string or wire-format data) is incomplete.
+/// finds the input (string or wire-format %data) is incomplete.
 ///
 /// An attempt of constructing a name from an empty string will trigger this
 /// exception.
@@ -168,13 +168,13 @@
 ///
 /// The \c Name class encapsulates DNS names.
 ///
-/// It provides interfaces to construct a name from string or wire-format data,
-/// transform a name into a string or wire-format data, compare two names, get
+/// It provides interfaces to construct a name from string or wire-format %data,
+/// transform a name into a string or wire-format %data, compare two names, get
 /// access to various properties of a name, etc.
 ///
-/// Notes to developers: Internally, a name object maintains the name data
+/// Notes to developers: Internally, a name object maintains the name %data
 /// in wire format as an instance of \c std::string.  Since many string
-/// implementations adopt copy-on-write data sharing, we expect this approach
+/// implementations adopt copy-on-write %data sharing, we expect this approach
 /// will make copying a name less expensive in typical cases.  If this is
 /// found to be a significant performance bottleneck later, we may reconsider
 /// the internal representation or perhaps the API.
@@ -187,9 +187,9 @@
 /// included.  In the BIND9 DNS library from which this implementation is
 /// derived, the offsets are optional, probably due to performance
 /// considerations (in fact, offsets can always be calculated from the name
-/// data, and in that sense are redundant).  In our implementation, however,
+/// %data, and in that sense are redundant).  In our implementation, however,
 /// we always build and maintain the offsets.  We believe we need more low
-/// level, specialized data structure and interface where we really need to
+/// level, specialized %data structure and interface where we really need to
 /// pursue performance, and would rather keep this generic API and
 /// implementation simpler.
 ///
@@ -233,21 +233,21 @@
     /// \param namestr A string representation of the name to be constructed.
     /// \param downcase Whether to convert upper case alphabets to lower case.
     explicit Name(const std::string& namestr, bool downcase = false);
-    /// Constructor from wire-format data.
+    /// Constructor from wire-format %data.
     ///
     /// The \c buffer parameter normally stores a complete DNS message
     /// containing the name to be constructed.  The current read position of
     /// the buffer points to the head of the name.
     ///
-    /// The input data may or may not be compressed; if it's compressed, this
+    /// The input %data may or may not be compressed; if it's compressed, this
     /// method will automatically decompress it.
     ///
-    /// If the given data does not represent a valid DNS name, an exception
+    /// If the given %data does not represent a valid DNS name, an exception
     /// of class \c DNSMessageFORMERR will be thrown.
     /// In addition, if resource allocation for the new name fails, a
     /// corresponding standard exception will be thrown.
     ///
-    /// \param buffer A buffer storing the wire format data.
+    /// \param buffer A buffer storing the wire format %data.
     /// \param downcase Whether to convert upper case alphabets to lower case.
     explicit Name(InputBuffer& buffer, bool downcase = false);
     ///
@@ -260,35 +260,35 @@
     /// \name Getter Methods
     ///
     //@{
-    /// \brief Provides one-byte name data in wire format at the specified
+    /// \brief Provides one-byte name %data in wire format at the specified
     /// position.
     ///
     /// This method returns the unsigned 8-bit value of wire-format \c Name
-    /// data at the given position from the head.
+    /// %data at the given position from the head.
     ///
     /// For example, if \c n is a \c Name object for "example.com",
     /// \c n.at(3) would return \c 'a', and \c n.at(7) would return \c 'e'.
     /// Note that \c n.at(0) would be 7 (decimal), the label length of
-    /// "example", instead of \c 'e', because it returns a data portion
+    /// "example", instead of \c 'e', because it returns a %data portion
     /// in wire-format.  Likewise, \c n.at(8) would return 3 (decimal)
     /// instead of <code>'.'</code>
     ///
     /// This method would be useful for an application to examine the
-    /// wire-format name data without dumping the data into a buffer,
-    /// which would involve data copies and would be less efficient.
+    /// wire-format name %data without dumping the %data into a buffer,
+    /// which would involve %data copies and would be less efficient.
     /// One common usage of this method would be something like this:
     /// \code for (size_t i = 0; i < name.getLength(); ++i) {
     ///     uint8_t c = name.at(i);
     ///     // do something with c
     /// } \endcode
     ///
-    /// Parameter \c pos must be in the valid range of the name data, that is,
+    /// Parameter \c pos must be in the valid range of the name %data, that is,
     /// must be less than \c Name.getLength().  Otherwise, an exception of
     /// class \c OutOfRange will be thrown.
     /// This method never throws an exception in other ways.
     ///
-    /// \param pos The position in the wire format name data to be returned.
-    /// \return An unsigned 8-bit integer corresponding to the name data
+    /// \param pos The position in the wire format name %data to be returned.
+    /// \return An unsigned 8-bit integer corresponding to the name %data
     /// at the position of \c pos.
     uint8_t at(size_t pos) const
     {
@@ -360,7 +360,7 @@
     /// <code>buffer.getCapacity() - buffer.getLength() >= Name::MAX_WIRE</code>
     /// then this method should not throw an exception.
     ///
-    /// \param buffer An output buffer to store the wire data.
+    /// \param buffer An output buffer to store the wire %data.
     void toWire(OutputBuffer& buffer) const;
     //@}
 
@@ -609,11 +609,108 @@
     return (root_name);
 }
 
+///
+/// \name Utility functions manipulating names.
+///
+//@{
+/// \brief Create an ancestor name of a given \c Name.
+///
+/// This function creates a new \c Name object that is an ancestor of
+/// \c source.   The new name is \c level labels upper than \c source.
+/// For example, when \c source is www.example.com,
+/// <code>createAncestorNameOf(source, 1)</code> will return a \c Name object
+/// for example.com.
+/// \c level can be 0, in which case this function returns a copy of the
+/// \c source name.
+/// The possible maximum value for \c level is
+/// <code>source.getLabelCount()-1</code>, in which case this function
+/// returns a root name.
+///
+/// One common expected usage of this function is to iterate over super
+/// domains of a given name, label by label, as shown in the following
+/// sample code:
+/// \code // if name is www.example.com...
+/// for (int i = 0; i < name.getLabelCount(); ++i) {
+///     Name upper_name(createAncestorNameOf(name, i));
+///     // upper_name will be www.example.com., example.com., com., and then .
+/// }
+/// \endcode
+///
+/// \c level must be smaller than the number of labels of \c source;
+/// otherwise an exception of class \c OutOfRange will be thrown.
+/// In addition, if resource allocation for the new name fails, a
+/// corresponding standard exception will be thrown.
+///
+/// Note to developers: probably as easily imagined, this function is a
+/// simple wrapper to one usage of the \c Name::split() method and is
+/// redundant in some sense.
+/// We provide this as a public function for convenience, however, because
+/// the expected usage shown above seems to be common, and the parameters
+/// to \c Name::split() to implement it may not be very intuitive.
+/// Another possible question about this function might be why this is not
+/// implemented as a public member function of the \c Name class.
+/// This is because we wanted to keep the class definition as simple as
+/// possible by limiting public members to something primitive to the class
+/// (being a wrapper of another member, this function is clearly not
+/// primitive).
+/// And, in fact, this is generally considered a better practice in C++;
+/// if we implemented this function as a member function, it might exploit
+/// its ability to access private class members for, e.g., performance
+/// reasons, which would make it harder to change the internal implementation
+/// of the class in future.
+/// One possible disadvantage of non member function approach is that
+/// it might be less efficient than a member function providing the same
+/// service.  At the moment we have no evidence that the performance overhead
+/// is a real issue, so we follow the common practice of the language.
+/// If, through performance benchmark in future, it turns out to be a
+/// significant bottleneck in critical operations, we may change the decision
+/// and may consider implementing it as a member function of the \c Name class.
+///
+/// \param source A \c Name for which the ancestor name is to be created.
+/// \param level The number of labels to be removed from \c source to create
+/// the ancestor name. (0 <= \c level < <code>source.getLabelCount()</code>)
+/// \return A new \c Name object to be created.
 Name
 createAncestorNameOf(const Name& source, unsigned int level);
 
+/// \brief Create a suffix name of a give \c Name.
+///
+/// This function creates a new \c Name object that shares the specified
+/// number (\c labels) of trailing labels of a given name (\c source).
+/// The trailing dot of \c source is counted as a single label.
+/// For example, when \c source is www.example.com,
+/// <code>createSuffixNameOf(source, 2)</code> will return a \c Name object
+/// for com. (including a trailing dot).
+///
+/// One common expected usage of this function is to iterate over super
+/// domains of a given name, label by label from the root to the given name,
+/// as shown in the following sample code:
+/// \code // if name is www.example.com...
+/// for (int i = 1; i <= name.getLabelCount(); ++i) {
+///     Name suffix_name(createSuffixNameOf(name, i));
+///     // suffix_name will be ., com., example.com., then www.example.com.
+/// }
+/// \endcode
+///
+/// \c labels must be a non-0 integer and must not exceed the number of
+/// labels of \c source;
+/// otherwise an exception of class \c OutOfRange will be thrown.
+/// In addition, if resource allocation for the new name fails, a
+/// corresponding standard exception will be thrown.
+///
+/// Note to developers: the same implementation decision as that for
+/// \c createAncestorNameOf applies to this function.
+/// See the description of that function for more details.
+///
+/// \param source A \c Name for which the suffix name is to be created.
+/// \param labels The number of trailing labels that the suffix name should
+///  share with \c source.
+/// (1 <= \c labels <= <code>source.getLabelCount()</code>)
+///
+/// \return A new \c Name object to be created.
 Name
 createSuffixNameOf(const Name& source, unsigned int labels);
+//@}
 
 ///
 /// \brief Insert the name as a string into stream.




More information about the bind10-changes mailing list