detailed description of the RRTTL class

git-svn-id: svn://bind10.isc.org/svn/bind10/branches/jinmei-dnsrrparams@462 e5f2f494-b856-4b98-b285-d166d9295462

src/lib/dns/cpp/rrttl.h

@@ -28,7 +28,8 @@ class OutputBuffer;
 class MessageRenderer;
 
 ///
-/// \brief TBD
+/// \brief A standard DNS module exception that is thrown if an RRTTL object
+/// is being constructed from an unrecognized string.
 ///
 class InvalidRRTTL : public Exception {
 public:
@@ -46,16 +47,39 @@ public:
         isc::dns::Exception(file, line, what) {}
 };
 
+///
+/// The \c RRTTL class encapsulates TTLs used in DNS resource records.
+///
+/// This is a straightforward class; an \c RRTTL object simply maintains a
+/// 32-bit unsigned integer corresponding to the TTL value.  The main purpose
+/// of this class is to provide convenient interfaces to convert a textual
+/// representation into the integer TTL value and vice versa, and to handle
+/// wire-format representations.
 class RRTTL {
 public:
     ///
     /// \name Constructors and Destructor
     ///
+    /// Note: We use the default copy constructor and the default copy
+    /// assignment operator intentionally.
     //@{
-    explicit RRTTL(uint32_t ttlval) : ttlval_(ttlval) {}
+    /// Constructor from an integer TTL value.
     ///
-    /// TODO: this version only accepts decimal TTL values.  We'll extend
-    /// it so that we can accept more convenient ones such as "2H" or "1D".
+    /// This constructor never throws an exception.
+    ///
+    /// \param ttlval An 32-bit integer of the RRTTL.
+    explicit RRTTL(uint32_t ttlval) : ttlval_(ttlval) {}
+    /// Constructor from a string.
+    ///
+    /// This version of the implementation only accepts decimal TTL values in
+    /// seconds.
+    /// In a near future version, we'll extend it so that we can accept more
+    /// convenient ones such as "2H" or "1D".
+    ///
+    /// If the given string is not recognized as a valid representation of
+    /// an RR TTL, an exception of class \c InvalidRRTTL will be thrown.
+    ///
+    /// \param ttlstr A string representation of the \c RRTTL
     explicit RRTTL(const std::string& ttlstr);
     /// Constructor from wire-format data.
     ///
@@ -69,41 +93,139 @@ public:
     /// \param buffer A buffer storing the wire format data.
     explicit RRTTL(InputBuffer& buffer);
     ///
-    /// We use the default copy constructor intentionally.
     //@}
-    /// We use the default copy assignment operator intentionally.
+
     ///
+    /// \name Converter methods
+    ///
+    //@{
+    /// \brief Convert the \c RRTTL to a string.
+    ///
+    /// This version of implementation simply converts the TTL value into the
+    /// numeric textual representation.  We may introduce more human-readable
+    /// format depending on the context in future versions.
+    ///
+    /// If resource allocation in rendering process fails, a corresponding
+    /// standard exception will be thrown.
+    ///
+    /// \return A string representation of the \c RRTTL.
     const std::string toText() const;
-    void toWire(OutputBuffer& buffer) const;
+    /// \brief Render the \c RRTTL in the wire format.
+    ///
+    /// This method renders the TTL value in network byte order via \c renderer,
+    /// which encapsulates output buffer and other rendering contexts.
+    ///
+    /// If resource allocation in rendering process fails, a corresponding
+    /// standard exception will be thrown.
+    ///
+    /// \param buffer An output buffer to store the wire data.
     void toWire(MessageRenderer& renderer) const;
+    /// \brief Render the \c RRTTL in the wire format.
+    ///
+    /// This method renders the TTL value in network byte order into the
+    /// \c buffer.
+    ///
+    /// If resource allocation in rendering process fails, a corresponding
+    /// standard exception will be thrown.
+    ///
+    /// \param renderer DNS message rendering context that encapsulates the
+    /// output buffer in which the RRTTL is to be stored.
+    void toWire(OutputBuffer& buffer) const;
+    //@}
+
+    ///
+    /// \name Getter Methods
+    ///
+    //@{
+    /// \brief Returns the TTL value as a 32-bit unsigned integer.
+    ///
+    /// This method never throws an exception.
+    ///
+    /// \return An 32-bit integer corresponding to the RRTTL.
     uint32_t getValue() const { return (ttlval_); }
+    //@}
 
     ///
     /// \name Comparison methods
     ///
+    /// Comparison between two \c RRTTL objects is performed in a
+    /// straightforward way, that is, comparing the corresponding TTL values
+    /// (which is the result of the \c getValue() method) as 32-bit unsigned
+    /// integers.
     //@{
+    /// \brief Return true iff two RRTTLs are equal.
+    ///
+    /// This method never throws an exception.
+    ///
+    /// \param other the \c RRTTL object to compare against.
     bool equals(const RRTTL& other) const
     { return (ttlval_ == other.ttlval_); }
+    /// \brief Same as \c equals().
     bool operator==(const RRTTL& other) const
     { return (ttlval_ == other.ttlval_); }
+    /// \brief Return true iff two RRTTLs are not equal.
+    ///
+    /// This method never throws an exception.
+    ///
+    /// \param other the \c RRTTL object to compare against.
     bool nequals(const RRTTL& other) const
     { return (ttlval_ != other.ttlval_); }
+    /// \brief Same as \c nequals().
     bool operator!=(const RRTTL& other) const
     { return (ttlval_ != other.ttlval_); }
+    /// \brief Less-than or equal comparison for RRTTL against \c other.
+    ///
+    /// This method never throws an exception.
+    ///
+    /// \param other the \c RRTTL object to compare against.
+    /// \return true if \c this RRTTL is less than or equal to the \c other;
+    /// otherwise false.
     bool leq(const RRTTL& other) const
     { return (ttlval_ <= other.ttlval_); }
-    bool geq(const RRTTL& other) const
-    { return (ttlval_ >= other.ttlval_); }
-    bool operator>=(const RRTTL& other) const
-    { return (ttlval_ >= other.ttlval_); }
+
+    /// Same as \c leq()
     bool operator<=(const RRTTL& other) const
     { return (ttlval_ <= other.ttlval_); }
+
+    /// \brief Greater-than or equal comparison for RRTTL against \c other.
+    ///
+    /// This method never throws an exception.
+    ///
+    /// \param other the \c RRTTL object to compare against.
+    /// \return true if \c this RRTTL is greater than or equal to the \c other;
+    /// otherwise false.
+    bool geq(const RRTTL& other) const
+    { return (ttlval_ >= other.ttlval_); }
+
+    /// Same as \c geq()
+    bool operator>=(const RRTTL& other) const
+    { return (ttlval_ >= other.ttlval_); }
+
+    /// \brief Less-than comparison for RRTTL against \c other.
+    ///
+    /// This method never throws an exception.
+    ///
+    /// \param other the \c RRTTL object to compare against.
+    /// \return true if \c this RRTTL is less than the \c other;
+    /// otherwise false.
     bool lthan(const RRTTL& other) const
     { return (ttlval_ < other.ttlval_); }
+
+    /// Same as \c lthan()
     bool operator<(const RRTTL& other) const
     { return (ttlval_ < other.ttlval_); }
+
+    /// \brief Greater-than comparison for RRTTL against \c other.
+    ///
+    /// This method never throws an exception.
+    ///
+    /// \param other the \c RRTTL object to compare against.
+    /// \return true if \c this RRTTL is greater than the \c other;
+    /// otherwise false.
     bool gthan(const RRTTL& other) const
     { return (ttlval_ > other.ttlval_); }
+
+    /// Same as \c gthan()
     bool operator>(const RRTTL& other) const
     { return (ttlval_ > other.ttlval_); }
     //@}
@@ -112,8 +234,22 @@ private:
     uint32_t ttlval_;
 };
 
+///
+/// \brief Insert the \c RRTTL as a string into stream.
+///
+/// This method convert the \c rrttl into a string and inserts it into the
+/// output stream \c os.
+///
+/// This function overloads the global operator<< to behave as described in
+/// ostream::operator<< but applied to \c RRTTL objects.
+///
+/// \param os A \c std::ostream object on which the insertion operation is
+/// performed.
+/// \param rrttl The \c RRTTL object output by the operation.
+/// \return A reference to the same \c std::ostream object referenced by
+/// parameter \c os after the insertion operation.
 std::ostream&
-operator<<(std::ostream& os, const RRTTL& rrtype);
+operator<<(std::ostream& os, const RRTTL& rrttl);
 }
 }
 #endif  // __RRTTL_H