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

[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:
/// Sets the ElementPtr at the given key
/// \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);
/// Remove the ElementPtr at the given key
......@@ -315,10 +316,11 @@ public:
/// Creates an Element from the given input stream, where we keep
/// 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
/// 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.
/// \return An ElementPtr that contains the element(s) specified
/// in the given input stream.
......@@ -548,18 +550,18 @@ void merge(ElementPtr element, ConstElementPtr other);
///
/// \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
/// output stream \c out.
///
/// This function overloads the global operator<< to behave as described in
/// 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.
/// \param e The \c ElementPtr object to insert.
/// \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);
bool operator==(const Element& a, const Element& b);
......
......@@ -99,7 +99,7 @@ namespace isc {
/// \brief Sets the default timeout for blocking reads
/// in this session to the given number of milliseconds
/// \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.
virtual void setTimeout(size_t milliseconds) = 0;
......
......@@ -53,6 +53,8 @@ namespace isc { namespace config {
/// Create a \c ModuleSpec instance with the given data as
/// the 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,
const bool check = true)
throw(ModuleSpecError);
......@@ -86,6 +88,8 @@ namespace isc { namespace config {
// configuration specification
/// Validates the given configuration data for this specification.
/// \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,
/// false otherwise.
bool validateConfig(isc::data::ConstElementPtr data,
......
......@@ -141,7 +141,7 @@ typedef SectionIterator<RRsetPtr> RRsetIterator;
/// - 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,
/// 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.
class Message {
public:
......@@ -155,8 +155,8 @@ public:
///
/// Only the defined constants are valid where a header flag is required
/// in this library (e.g., in \c Message::setHeaderFlag()).
/// Since these are enum constants, however, invalid value could be passed
/// via casting without an error at compilation time.
/// Since these are enum constants, however, an invalid value could be
/// passed via casting without an error at compilation time.
/// It is generally the callee's responsibility to check and reject invalid
/// values.
/// Of course, applications shouldn't pass invalid values even if the
......@@ -168,7 +168,7 @@ public:
/// specified flag in the second 16 bits of the DNS Header section
/// in order to make the internal implementation simpler.
/// 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
/// must solely use the enum representations.
/// Any usage based on the assumption of the underlying values is invalid
......
......@@ -54,13 +54,13 @@ typedef boost::shared_ptr<const Question> ConstQuestionPtr;
/// class.
/// 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;
/// 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,
/// 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.
/// 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.
/// 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
......@@ -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
/// \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
/// straightforward implementation should suffice for any use cases
/// 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
/// 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
/// 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