[4234] doxygen fixes last pass

doc/Doxyfile

@@ -652,8 +652,10 @@ INPUT                  = ../src/bin/d2 \
                          ../src/bin/sockcreator \
                          ../src/bin/lfc \
                          ../src/hooks/dhcp/user_chk \
+                         ../src/lib/asiodns \
                          ../src/lib/asiolink \
                          ../src/lib/cc \
+                         ../src/lib/cfgrpt \
                          ../src/lib/config \
                          ../src/lib/cryptolink \
                          ../src/lib/dhcp \
@@ -666,10 +668,15 @@ INPUT                  = ../src/bin/d2 \
                          ../src/lib/hooks \
                          ../src/lib/log \
                          ../src/lib/log/compiler \
+                         ../src/lib/log/interprocess \
+                         ../src/lib/stats \
                          ../src/lib/testutils \
                          ../src/lib/util \
+                         ../src/lib/util/encode \
                          ../src/lib/util/io \
+                         ../src/lib/util/random \
                          ../src/lib/util/threads \
+                         ../src/lib/util/unittests \
                          devel
 
 # This tag can be used to specify the character encoding of the source files
@@ -706,7 +713,9 @@ RECURSIVE              = NO
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                =
+EXCLUDE                = ../src/lib/dns/master_lexer.cc \
+                         ../src/lib/dns/rdataclass.cc \
+                         ../src/lib/eval/lexer.cc
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded

src/bin/dhcp4/dhcp4_srv.h

@@ -425,7 +425,7 @@ protected:
     ///
     /// This method processes incoming DHCPDECLINE. In particular, it extracts
     /// Requested IP Address option, checks that the address really belongs to
-    /// the client and if it does, calls @ref declineLease().
+    /// the client and if it does, calls @ref declineLease.
     ///
     /// @param decline message received from client
     void processDecline(Pkt4Ptr& decline);
@@ -566,6 +566,7 @@ private:
     /// server's response.
     void processHostnameOption(Dhcpv4Exchange& ex);
 
+    /// @anchor declineLease
     /// @brief Marks lease as declined.
     ///
     /// This method moves a lease to declined state with all the steps involved:
@@ -730,7 +731,7 @@ protected:
     ///
     /// @note This is done in two phases: first the content of the
     /// vendor-class-identifier option is used as a class, by
-    /// calling @ref classifyByVendor(). Second classification match
+    /// calling @ref classifyByVendor. Second classification match
     /// expressions are evaluated. The resulting classes will be stored
     /// in the packet (see @ref isc::dhcp::Pkt4::classes_ and
     /// @ref isc::dhcp::Pkt4::inClass).
@@ -758,6 +759,7 @@ protected:
 
 private:
 
+    /// @anchor classifyByVendor
     /// @brief Assign class using vendor-class-identifier option
     ///
     /// @note This is the first part of @ref classifyPacket

src/bin/dhcp4/json_config_parser.cc

@@ -108,6 +108,7 @@ protected:
     }
 };
 
+/// @anchor Subnet4ConfigParser
 /// @brief This class parses a single IPv4 subnet.
 ///
 /// This is the IPv4 derivation of the SubnetConfigParser class and it parses

src/bin/dhcp6/dhcp6_srv.h

@@ -623,7 +623,7 @@ protected:
     ///
     /// @note This is done in two phases: first the content of the
     /// vendor-class-identifier option is used as a class, by
-    /// calling @ref classifyByVendor(). Second classification match
+    /// calling @ref classifyByVendor-decl. Second classification match
     /// expressions are evaluated. The resulting classes will be stored
     /// in the packet (see @ref isc::dhcp::Pkt6::classes_ and
     /// @ref isc::dhcp::Pkt6::inClass).
@@ -729,6 +729,7 @@ protected:
 
 private:
 
+    /// @anchor classifyByVendor-decl
     /// @brief Assign class using vendor-class-identifier option
     ///
     /// @note This is the first part of @ref classifyPacket

src/bin/dhcp6/json_config_parser.cc

@@ -313,6 +313,7 @@ private:
     PoolStoragePtr pools_;
 };
 
+/// @anchor Subnet6ConfigParser
 /// @brief This class parses a single IPv6 subnet.
 ///
 /// This is the IPv6 derivation of the SubnetConfigParser class and it parses

src/lib/asiodns/io_fetch.h

@@ -144,8 +144,20 @@ public:
     ///  with above constructor which has only question section. All
     ///  other parameters are same.
     ///
+    /// \param protocol Fetch protocol, either IOFetch::TCP or IOFetch::UDP
+    /// \param service I/O Service object to handle the asynchronous
+    ///        operations.
     /// \param query_message the shared_ptr to a full query message
     ///        got from a query client.
+    /// \param address IP address of upstream server
+    /// \param port Port to which to connect on the upstream server
+    /// \param buff Output buffer into which the response (in wire format)
+    ///        is written (if a response is received).
+    /// \param cb Callback object containing the callback to be called when we
+    ///        terminate.  The caller is responsible for managing this object
+    ///        and deleting it if necessary.
+    /// \param wait Timeout for the fetch (in ms).  The default value of
+    ///        -1 indicates no timeout.
     IOFetch(Protocol protocol, isc::asiolink::IOService& service,
         isc::dns::ConstMessagePtr query_message,
         const isc::asiolink::IOAddress& address,

src/lib/dhcpsrv/alloc_engine.h

@@ -524,7 +524,7 @@ public:
     /// declined state). Therefore remove_leases parameter is ignored for
     /// declined leases. They are always removed.
     ///
-    /// Also, for declined leases @ref reclaimDeclined(const Lease6Ptr&) is
+    /// Also, for declined leases @ref reclaimDeclined-Lease6 is
     /// called. It conducts several declined specific operation (extra log
     /// entry, stats dump, hooks).
     ///
@@ -582,7 +582,7 @@ public:
     /// declined state). Therefore remove_leases parameter is ignored for
     /// declined leases. They are always removed.
     ///
-    /// Also, for declined leases @ref reclaimDeclined(const Lease4Ptr&) is
+    /// Also, for declined leases @ref reclaimDeclined-Lease4 is
     /// called. It conductsseveral declined specific operation (extra log
     /// entry, stats dump, hooks).
     ///
@@ -876,6 +876,7 @@ private:
                                 const boost::function<void (const LeasePtrType&)>&
                                 lease_update_fun) const;
 
+    /// @anchor reclaimDeclined-Lease4
     /// @brief Conducts steps necessary for reclaiming declined IPv4 lease.
     ///
     /// These are the additional steps required when recoving a declined lease:
@@ -888,6 +889,7 @@ private:
     ///         to keep it)
     bool reclaimDeclined(const Lease4Ptr& lease);
 
+    /// @anchor reclaimDeclined-Lease6
     /// @brief Conducts steps necessary for reclaiming declined IPv6 lease.
     ///
     /// These are the additional steps required when recoving a declined lease:

src/lib/dhcpsrv/cfg_iface.h

@@ -97,6 +97,42 @@ public:
 /// but it doesn't verify that the address family value passed as @c uint16_t
 /// parameter is equal to one of them. It is a callers responsibility to
 /// guarantee that the address family value is correct.
+///
+/// The interface name is passed as an argument of the @ref CfgIface::use
+/// function which controls the selection of the interface on which the
+/// DHCP queries should be received by the server. The interface name
+/// passed as the argument of this function may appear in one of the following
+/// formats:
+/// - interface-name, e.g. eth0
+/// - interface-name/address, e.g. eth0/2001:db8:1::1 or eth0/192.168.8.1
+///
+/// Extraneous spaces surrounding the interface name and/or address
+/// are accepted. For example: eth0 / 2001:db8:1::1 will be accepted.
+///
+/// When only interface name is specified (without an address) it is allowed
+/// to use the "wildcard" interface name (*) which indicates that the server
+/// should open sockets on all interfaces. When IPv6 is in use, the sockets
+/// will be bound to the link local addresses. Wildcard interface names are
+/// not allowed when specifying a unicast address. For example:
+/// */2001:db8:1::1 is not allowed.
+///
+/// The DHCPv6 configuration accepts simultaneous use of the "interface-name"
+/// and "interface-name/address" tuple for the same interface, e.g.
+/// "eth0", "eth0/2001:db8:1::1" specifies that the server should open a
+/// socket and bind to link local address as well as open a socket bound to
+/// the specified unicast address.
+///
+/// The DHCPv4 configuration doesn't accept the simulatenous use of the
+/// "interface-name" and the "interface-name/address" tuple for the
+/// given interface. When the "interface-name" is specified it implies
+/// that the sockets will be opened on for all addresses configured on
+/// this interface. If the tuple of "interface-name/address" is specified
+/// there will be only one socket opened and bound to the specified address.
+/// This socket will be configured to listen to the broadcast messages
+/// reaching the interface as well as unicast messages sent to the address
+/// to which it is bound. It is allowed to select multiple addresses on the
+/// particular interface explicitly, e.g. "eth0/192.168.8.1",
+/// "eth0/192.168.8.2".
 class CfgIface {
 public:
 
@@ -149,40 +185,7 @@ public:
 
     /// @brief Select interface to be used to receive DHCP traffic.
     ///
-    /// This function controls the selection of the interface on which the
-    /// DHCP queries should be received by the server. The interface name
-    /// passed as the argument of this function may appear in one of the following
-    /// formats:
-    /// - interface-name, e.g. eth0
-    /// - interface-name/address, e.g. eth0/2001:db8:1::1 or eth0/192.168.8.1
-    ///
-    /// Extraneous spaces surrounding the interface name and/or address
-    /// are accepted. For example: eth0 / 2001:db8:1::1 will be accepted.
-    ///
-    /// When only interface name is specified (without an address) it is allowed
-    /// to use the "wildcard" interface name (*) which indicates that the server
-    /// should open sockets on all interfaces. When IPv6 is in use, the sockets
-    /// will be bound to the link local addresses. Wildcard interface names are
-    /// not allowed when specifying a unicast address. For example:
-    /// */2001:db8:1::1 is not allowed.
-    ///
-    /// The DHCPv6 configuration accepts simultaneous use of the "interface-name"
-    /// and "interface-name/address" tuple for the same interface, e.g.
-    /// "eth0", "eth0/2001:db8:1::1" specifies that the server should open a
-    /// socket and bind to link local address as well as open a socket bound to
-    /// the specified unicast address.
-    ///
-    /// The DHCPv4 configuration doesn't accept the simulatenous use of the
-    /// "interface-name" and the "interface-name/address" tuple for the
-    /// given interface. When the "interface-name" is specified it implies
-    /// that the sockets will be opened on for all addresses configured on
-    /// this interface. If the tuple of "interface-name/address" is specified
-    /// there will be only one socket opened and bound to the specified address.
-    /// This socket will be configured to listen to the broadcast messages
-    /// reaching the interface as well as unicast messages sent to the address
-    /// to which it is bound. It is allowed to select multiple addresses on the
-    /// particular interface explicitly, e.g. "eth0/192.168.8.1",
-    /// "eth0/192.168.8.2".
+    /// @ref CfgIface for a detail explaination of the interface name argument.
     ///
     /// @param family Address family (AF_INET or AF_INET6).
     /// @param iface_name Explicit interface name, a wildcard name (*) of

src/lib/dns/rdata/generic/opt_41.h

@@ -73,7 +73,7 @@ public:
     /// \param data The OPTION-DATA field of the pseudo RR.
     /// \param length The size of the \c data argument. OPTION-LENGTH is
     /// set to this size.
-    /// \throw \c isc::InvalidParameter if this pseudo RR would cause
+    /// \throw isc::InvalidParameter if this pseudo RR would cause
     /// the OPT RDATA to overflow its RDLENGTH.
     void appendPseudoRR(uint16_t code, const uint8_t* data, uint16_t length);
 

src/lib/dns/rdataclass.h

@@ -1692,7 +1692,7 @@ public:
     /// \param data The OPTION-DATA field of the pseudo RR.
     /// \param length The size of the \c data argument. OPTION-LENGTH is
     /// set to this size.
-    /// \throw \c isc::InvalidParameter if this pseudo RR would cause
+    /// \throw isc::InvalidParameter if this pseudo RR would cause
     /// the OPT RDATA to overflow its RDLENGTH.
     void appendPseudoRR(uint16_t code, const uint8_t* data, uint16_t length);
 

src/lib/dns/rrset.h

@@ -217,7 +217,7 @@ public:
     ///
     /// \return The length of the wire format representation of the
     /// \c AbstractRRset.
-    /// \throw \c EmptyRRset if the \c AbstractRRset is empty.
+    /// \throw EmptyRRset if the \c AbstractRRset is empty.
     virtual uint16_t getLength() const = 0;
 
     /// \brief Returns the owner name of the \c RRset.
@@ -678,7 +678,7 @@ public:
     ///
     /// \return The length of the wire format representation of the
     /// \c BasicRRset.
-    /// \throw \c EmptyRRset if the \c BasicRRset is empty.
+    /// \throw EmptyRRset if the \c BasicRRset is empty.
     virtual uint16_t getLength() const;
 
     /// \brief Returns the owner name of the \c RRset.
@@ -863,7 +863,7 @@ public:
     ///
     /// \return The length of the wire format representation of the
     /// \c RRset.
-    /// \throw \c EmptyRRset if the \c RRset is empty.
+    /// \throw EmptyRRset if the \c RRset is empty.
     virtual uint16_t getLength() const;
 
     /// \brief Render the RRset in the wire format with name compression and

src/lib/stats/observation.h

@@ -134,7 +134,7 @@ class Observation {
     ///
     /// @param value duration value observed
     /// @throw InvalidStatType if statistic is not time duration
-    void setValue(const StatsDuration& duration);
+    void setValue(const StatsDuration& value);
 
     /// @brief Records absolute string observation
     ///

src/lib/stats/stats_mgr.h

@@ -63,7 +63,7 @@ namespace stats {
 ///   either all or nothing. Adding logging entries only when necessary
 ///   in the code that uses StatsMgr gives better granularity.
 ///
-/// If this decision is revisited in the futere, the most universal places
+/// If this decision is revisited in the future, the most universal places
 /// for adding logging have been marked in @ref addValueInternal and
 /// @ref setValueInternal.
 class StatsMgr : public boost::noncopyable {
@@ -125,7 +125,7 @@ class StatsMgr : public boost::noncopyable {
     /// @param name name of the observation
     /// @param value duration value observed
     /// @throw InvalidStatType if statistic is not time duration
-    void addValue(const std::string& name, const StatsDuration& time);
+    void addValue(const std::string& name, const StatsDuration& value);
 
     /// @brief Records incremental string observation.
     ///
@@ -256,12 +256,12 @@ class StatsMgr : public boost::noncopyable {
     ///
     /// @param name name of the command (ignored, should be "statistic-get")
     /// @param params structure containing a map that contains "name"
-    /// @param return answer containing details of specified statistic
+    /// @return answer containing details of specified statistic
     static isc::data::ConstElementPtr
     statisticGetHandler(const std::string& name,
                         const isc::data::ConstElementPtr& params);
 
-    /// @param Handles statistic-reset command
+    /// @brief Handles statistic-reset command
     ///
     /// This method handles statistic-reset command, which resets value
     /// of a given statistic. It expects one parameter stored in params map:
@@ -274,12 +274,12 @@ class StatsMgr : public boost::noncopyable {
     ///
     /// @param name name of the command (ignored, should be "statistic-reset")
     /// @param params structure containing a map that contains "name"
-    /// @param return answer containing confirmation
+    /// @return answer containing confirmation
     static isc::data::ConstElementPtr
     statisticResetHandler(const std::string& name,
                           const isc::data::ConstElementPtr& params);
 
-    /// @param Handles statistic-remove command
+    /// @brief Handles statistic-remove command
     ///
     /// This method handles statistic-reset command, which removes a given
     /// statistic completely. It expects one parameter stored in params map:
@@ -292,7 +292,7 @@ class StatsMgr : public boost::noncopyable {
     ///
     /// @param name name of the command (ignored, should be "statistic-remove")
     /// @param params structure containing a map that contains "name" element
-    /// @param return answer containing confirmation
+    /// @return answer containing confirmation
     static isc::data::ConstElementPtr
     statisticRemoveHandler(const std::string& name,
                            const isc::data::ConstElementPtr& params);
@@ -304,7 +304,7 @@ class StatsMgr : public boost::noncopyable {
     ///
     /// @param name name of the command (ignored, should be "statistic-get-all")
     /// @param params ignored
-    /// @param return answer containing values of all statistic
+    /// @return answer containing values of all statistic
     static isc::data::ConstElementPtr
     statisticGetAllHandler(const std::string& name,
                            const isc::data::ConstElementPtr& params);
@@ -316,7 +316,7 @@ class StatsMgr : public boost::noncopyable {
     ///
     /// @param name name of the command (ignored, should be "statistic-reset-all")
     /// @param params ignored
-    /// @param return answer confirming success of this operation
+    /// @return answer confirming success of this operation
     static isc::data::ConstElementPtr
     statisticResetAllHandler(const std::string& name,
                              const isc::data::ConstElementPtr& params);
@@ -328,7 +328,7 @@ class StatsMgr : public boost::noncopyable {
     ///
     /// @param name name of the command (ignored, should be "statistic-remove-all")
     /// @param params ignored
-    /// @param return answer confirming success of this operation
+    /// @return answer confirming success of this operation
     static isc::data::ConstElementPtr
     statisticRemoveAllHandler(const std::string& name,
                               const isc::data::ConstElementPtr& params);
@@ -337,6 +337,7 @@ class StatsMgr : public boost::noncopyable {
 
  private:
 
+    /// @anchor setValueInternal
     /// @brief Sets a given statistic to specified value (internal version).
     ///
     /// This template method sets statistic identified by name to a value
@@ -360,6 +361,7 @@ class StatsMgr : public boost::noncopyable {
         }
     }
 
+    /// @anchor addValueInternal
     /// @brief Adds specified value to a given statistic (internal version).
     ///
     /// This template method adds specified value to a given statistic (identified
@@ -393,6 +395,7 @@ class StatsMgr : public boost::noncopyable {
     /// method.
     StatsMgr();
 
+    /// @anchor addObservation
     /// @brief Adds a new observation.
     ///
     /// That's an utility method used by public @ref setValue() and