Commit 5f59f72e authored by Jeremy C. Reed's avatar Jeremy C. Reed
Browse files

[jreed-doxygen] doxygen fixes and improvements.

Add missing definitions.
Fix typos.
Add or change some punctuation.
Minor grammar fixes.
Quote a term so doesn't become a link.
parent 1e5b246a
...@@ -222,6 +222,7 @@ public: ...@@ -222,6 +222,7 @@ public:
/// Sets the ElementPtr at the given key /// Sets the ElementPtr at the given key
/// \param name The key of the Element to set /// \param name The key of the Element to set
/// \param element The ElementPtr to set at the given key.
virtual void set(const std::string& name, ConstElementPtr element); virtual void set(const std::string& name, ConstElementPtr element);
/// Remove the ElementPtr at the given key /// Remove the ElementPtr at the given key
...@@ -315,10 +316,11 @@ public: ...@@ -315,10 +316,11 @@ public:
/// Creates an Element from the given input stream, where we keep /// Creates an Element from the given input stream, where we keep
/// track of the location in the stream for error reporting. /// track of the location in the stream for error reporting.
/// ///
/// \param in The string to parse the element from /// \param in The string to parse the element from.
/// \param file The input file name.
/// \param line A reference to the int where the function keeps /// \param line A reference to the int where the function keeps
/// track of the current line. /// track of the current line.
/// \param line A reference to the int where the function keeps /// \param pos A reference to the int where the function keeps
/// track of the current position within the current line. /// track of the current position within the current line.
/// \return An ElementPtr that contains the element(s) specified /// \return An ElementPtr that contains the element(s) specified
/// in the given input stream. /// in the given input stream.
...@@ -548,18 +550,18 @@ void merge(ElementPtr element, ConstElementPtr other); ...@@ -548,18 +550,18 @@ void merge(ElementPtr element, ConstElementPtr other);
/// ///
/// \brief Insert the Element as a string into stream. /// \brief Insert the Element as a string into stream.
/// ///
/// This method converts the \c ElemetPtr into a string with /// This method converts the \c ElementPtr into a string with
/// \c Element::str() and inserts it into the /// \c Element::str() and inserts it into the
/// output stream \c out. /// output stream \c out.
/// ///
/// This function overloads the global operator<< to behave as described in /// This function overloads the global operator<< to behave as described in
/// ostream::operator<< but applied to \c ElementPtr objects. /// ostream::operator<< but applied to \c ElementPtr objects.
/// ///
/// \param os A \c std::ostream object on which the insertion operation is /// \param out A \c std::ostream object on which the insertion operation is
/// performed. /// performed.
/// \param e The \c ElementPtr object to insert. /// \param e The \c ElementPtr object to insert.
/// \return A reference to the same \c std::ostream object referenced by /// \return A reference to the same \c std::ostream object referenced by
/// parameter \c os after the insertion operation. /// parameter \c out after the insertion operation.
std::ostream& operator<<(std::ostream& out, const Element& e); std::ostream& operator<<(std::ostream& out, const Element& e);
bool operator==(const Element& a, const Element& b); bool operator==(const Element& a, const Element& b);
......
...@@ -99,7 +99,7 @@ namespace isc { ...@@ -99,7 +99,7 @@ namespace isc {
/// \brief Sets the default timeout for blocking reads /// \brief Sets the default timeout for blocking reads
/// in this session to the given number of milliseconds /// in this session to the given number of milliseconds
/// \param milliseconds the timeout for blocking reads in /// \param milliseconds the timeout for blocking reads in
/// milliseconds, if this is set to 0, reads will block /// milliseconds; if this is set to 0, reads will block
/// forever. /// forever.
virtual void setTimeout(size_t milliseconds) = 0; virtual void setTimeout(size_t milliseconds) = 0;
......
...@@ -53,6 +53,8 @@ namespace isc { namespace config { ...@@ -53,6 +53,8 @@ namespace isc { namespace config {
/// Create a \c ModuleSpec instance with the given data as /// Create a \c ModuleSpec instance with the given data as
/// the specification /// the specification
/// \param e The Element containing the data specification /// \param e The Element containing the data specification
/// \param check If false, the module specification in the file
/// is not checked to be of the correct form.
explicit ModuleSpec(isc::data::ConstElementPtr e, explicit ModuleSpec(isc::data::ConstElementPtr e,
const bool check = true) const bool check = true)
throw(ModuleSpecError); throw(ModuleSpecError);
...@@ -86,6 +88,8 @@ namespace isc { namespace config { ...@@ -86,6 +88,8 @@ namespace isc { namespace config {
// configuration specification // configuration specification
/// Validates the given configuration data for this specification. /// Validates the given configuration data for this specification.
/// \param data The base \c Element of the data to check /// \param data The base \c Element of the data to check
/// \param full If true, all non-optional configuration parameters
/// must be specified.
/// \return true if the data conforms to the specification, /// \return true if the data conforms to the specification,
/// false otherwise. /// false otherwise.
bool validateConfig(isc::data::ConstElementPtr data, bool validateConfig(isc::data::ConstElementPtr data,
......
...@@ -141,7 +141,7 @@ typedef SectionIterator<RRsetPtr> RRsetIterator; ...@@ -141,7 +141,7 @@ typedef SectionIterator<RRsetPtr> RRsetIterator;
/// - We may want to provide an "iterator" for all RRsets/RRs for convenience. /// - We may want to provide an "iterator" for all RRsets/RRs for convenience.
/// This will be for applications that do not care about performance much, /// This will be for applications that do not care about performance much,
/// so the implementation can only be moderately efficient. /// so the implementation can only be moderately efficient.
/// - may want to provide a "find" method for a specified type /// - We may want to provide a "find" method for a specified type
/// of RR in the message. /// of RR in the message.
class Message { class Message {
public: public:
...@@ -155,8 +155,8 @@ public: ...@@ -155,8 +155,8 @@ public:
/// ///
/// Only the defined constants are valid where a header flag is required /// Only the defined constants are valid where a header flag is required
/// in this library (e.g., in \c Message::setHeaderFlag()). /// in this library (e.g., in \c Message::setHeaderFlag()).
/// Since these are enum constants, however, invalid value could be passed /// Since these are enum constants, however, an invalid value could be
/// via casting without an error at compilation time. /// passed via casting without an error at compilation time.
/// It is generally the callee's responsibility to check and reject invalid /// It is generally the callee's responsibility to check and reject invalid
/// values. /// values.
/// Of course, applications shouldn't pass invalid values even if the /// Of course, applications shouldn't pass invalid values even if the
...@@ -168,7 +168,7 @@ public: ...@@ -168,7 +168,7 @@ public:
/// specified flag in the second 16 bits of the DNS Header section /// specified flag in the second 16 bits of the DNS Header section
/// in order to make the internal implementation simpler. /// in order to make the internal implementation simpler.
/// For example, \c HEADERFLAG_QR is defined to be 0x8000 as the QR /// For example, \c HEADERFLAG_QR is defined to be 0x8000 as the QR
/// bit is the most significant bit of the 2nd 16 bits of the header. /// bit is the most significant bit of the second 16 bits of the header.
/// However, applications should not assume this coincidence and /// However, applications should not assume this coincidence and
/// must solely use the enum representations. /// must solely use the enum representations.
/// Any usage based on the assumption of the underlying values is invalid /// Any usage based on the assumption of the underlying values is invalid
......
...@@ -54,13 +54,13 @@ typedef boost::shared_ptr<const Question> ConstQuestionPtr; ...@@ -54,13 +54,13 @@ typedef boost::shared_ptr<const Question> ConstQuestionPtr;
/// class. /// class.
/// This may look odd in that an "RRset" and "Question" are similar from the /// This may look odd in that an "RRset" and "Question" are similar from the
/// protocol point of view: Both are used as a semantics unit of DNS messages; /// protocol point of view: Both are used as a semantics unit of DNS messages;
/// both share the same set of components, name, RR type and RR class. /// both share the same set of components (name, RR type and RR class).
/// ///
/// In fact, BIND9 didn't introduce a separate data structure for Questions, /// In fact, BIND9 didn't introduce a separate data structure for Questions,
/// and use the same \c "rdataset" structure for both RRsets and Questions. /// and use the same \c "rdataset" structure for both RRsets and Questions.
/// We could take the same approach, but chose to adopt the different design. /// We could take the same approach, but chose to adopt the different design.
/// One reason for that is because a Question and an RRset are still /// One reason for that is because a Question and an RRset are still
/// different, and a Question might not be cleanly defined if (e.g.) it were /// different, and a Question might not be cleanly defined, e.g., if it were
/// a derived class of some "RRset-like" class. /// a derived class of some "RRset-like" class.
/// For example, we couldn't give a reasonable semantics for \c %getTTL() or /// For example, we couldn't give a reasonable semantics for \c %getTTL() or
/// \c %setTTL() methods for a Question, since it's not associated with the /// \c %setTTL() methods for a Question, since it's not associated with the
...@@ -74,14 +74,14 @@ typedef boost::shared_ptr<const Question> ConstQuestionPtr; ...@@ -74,14 +74,14 @@ typedef boost::shared_ptr<const Question> ConstQuestionPtr;
/// ///
/// On the other hand, we do not expect a strong need for customizing the /// On the other hand, we do not expect a strong need for customizing the
/// \c Question class, unlike the RRset. /// \c Question class, unlike the RRset.
/// Handling the Question section of a DNS message is relatively a /// Handling the "Question" section of a DNS message is relatively a
/// simple work comparing to RRset-involved operations, so a unified /// simple work comparing to RRset-involved operations, so a unified
/// straightforward implementation should suffice for any use cases /// straightforward implementation should suffice for any use cases
/// including performance sensitive ones. /// including performance sensitive ones.
/// ///
/// We may, however, still want to have customized version of Question /// We may, however, still want to have a customized version of Question
/// for, e.g, highly optimized behavior, and may revisit this design choice /// for, e.g, highly optimized behavior, and may revisit this design choice
/// as we have more experiences with this implementation. /// as we have more experience with this implementation.
/// ///
/// One disadvantage of defining RRsets and Questions as unrelated classes /// One disadvantage of defining RRsets and Questions as unrelated classes
/// is that we cannot handle them in a polymorphic way. /// is that we cannot handle them in a polymorphic way.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment