From 7e612258d20ae92677849fa5c257d7b2c8c811c8 Mon Sep 17 00:00:00 2001
From: Francis Dupont <fdupont@isc.org>
Date: Fri, 11 Dec 2015 15:23:36 +0100
Subject: [PATCH] [4234] doxygen cleanup first pass

---
 src/bin/d2/d_controller.h                         |  2 +-
 src/bin/dhcp4/dhcp4.dox                           |  4 ++--
 src/bin/dhcp4/dhcp4_srv.h                         |  5 ++---
 src/bin/dhcp6/dhcp6.dox                           |  4 ++--
 src/bin/dhcp6/dhcp6_srv.h                         |  4 ++--
 src/lib/asiolink/io_address.h                     |  2 ++
 src/lib/dhcpsrv/alloc_engine.h                    | 14 +++++++-------
 src/lib/dhcpsrv/alloc_engine_log.cc               |  2 +-
 src/lib/dhcpsrv/alloc_engine_log.h                |  4 ++--
 src/lib/dhcpsrv/client_class_def.h                |  2 +-
 src/lib/dhcpsrv/hosts_log.cc                      |  2 +-
 src/lib/dhcpsrv/parsers/client_class_def_parser.h |  4 ++--
 src/lib/dhcpsrv/parsers/dhcp_parsers.h            |  1 -
 src/lib/dns/rdataclass.h                          |  4 ++--
 src/lib/dns/rrclass-placeholder.h                 |  6 +++---
 src/lib/dns/rrclass.h                             |  6 +++---
 src/lib/dns/rrtype-placeholder.h                  |  6 +++---
 src/lib/dns/rrtype.h                              |  6 +++---
 src/lib/dns/tsigkey.h                             |  2 ++
 src/lib/util/csv_file.h                           |  2 +-
 src/lib/util/versioned_csv_file.h                 |  5 ++---
 21 files changed, 44 insertions(+), 43 deletions(-)

diff --git a/src/bin/d2/d_controller.h b/src/bin/d2/d_controller.h
index 593511d812..4ae7a5b71b 100644
--- a/src/bin/d2/d_controller.h
+++ b/src/bin/d2/d_controller.h
@@ -119,7 +119,7 @@ public:
     virtual ~DControllerBase();
 
     /// @brief returns Kea version on stdout and exit.
-    /// redeclaration/redefinition. @ref Daemon::getVersion()
+    /// redeclaration/redefinition. @ref isc::dhcp::Daemon::getVersion()
     static std::string getVersion(bool extended);
  
     /// @brief Acts as the primary entry point into the controller execution
diff --git a/src/bin/dhcp4/dhcp4.dox b/src/bin/dhcp4/dhcp4.dox
index 3a02fbf2a2..8f68f05a8d 100644
--- a/src/bin/dhcp4/dhcp4.dox
+++ b/src/bin/dhcp4/dhcp4.dox
@@ -39,7 +39,7 @@ from the common configuration parsers and customize their behavior. For
 example: the @c Subnet4ConfigParser is used to parse parameters
 describing a single subnet. It derives from the @c
 isc::dhcp::SubnetConfigParser, which implements the common base for both
-DHCPv4 and DHCPv6 subnets. The @ref isc::dhcp::Subnet4ConfigParser
+DHCPv4 and DHCPv6 subnets. The @ref Subnet4ConfigParser
 implements the @c initSubnet abstract method, which creates an instance of
 the DHCPv4 subnet. This method is invoked by the parent class.
 
@@ -233,7 +233,7 @@ library. See ticket #3275. The class specific behavior is:
 - docsis3.0 packets have file field set to the content of the boot-file-name option
 - eRouter1.0 packets have siaddr (next server) field cleared
 
-Aforementioned modifications are conducted in @ref isc::dhcp::Dhcpv4Srv::classSpecificProcessing.
+Aforementioned modifications are conducted in @ref isc::dhcp::Dhcpv4Srv::vendorClassSpecificProcessing.
 
 It is possible to define class restrictions in subnet, so a given subnet is only
 accessible to clients that belong to a given class. That is implemented as isc::dhcp::Pkt4::classes_
diff --git a/src/bin/dhcp4/dhcp4_srv.h b/src/bin/dhcp4/dhcp4_srv.h
index a604ae75a6..a3e28c7705 100644
--- a/src/bin/dhcp4/dhcp4_srv.h
+++ b/src/bin/dhcp4/dhcp4_srv.h
@@ -577,8 +577,7 @@ private:
     ///
     /// @param lease lease to be declined
     /// @param decline client's message
-    void
-    declineLease(const Lease4Ptr& lease, const Pkt4Ptr& decline);
+    void declineLease(const Lease4Ptr& lease, const Pkt4Ptr& decline);
 
 protected:
 
@@ -731,7 +730,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).
diff --git a/src/bin/dhcp6/dhcp6.dox b/src/bin/dhcp6/dhcp6.dox
index d84bc30e53..82bcb4da13 100644
--- a/src/bin/dhcp6/dhcp6.dox
+++ b/src/bin/dhcp6/dhcp6.dox
@@ -39,7 +39,7 @@ from the common configuration parsers and customize their behavior. For
 example: the @c Subnet6ConfigParser is used to parse parameters
 describing a single subnet. It derives from the @c
 isc::dhcp::SubnetConfigParser, which implements the common base for both
-DHCPv4 and DHCPv6 subnets. The @ref isc::dhcp::Subnet6ConfigParser
+DHCPv4 and DHCPv6 subnets. The @ref Subnet6ConfigParser
 implements the @c initSubnet abstract method, which creates an instance of
 the DHCPv6 subnet. This method is invoked by the parent class.
 
@@ -236,7 +236,7 @@ check whether a packet belongs to given class, isc::dhcp::Pkt6::inClass method s
 be used.
 
 Currently there is no class behavior coded in DHCPv6, hence no v6 equivalent of
-@ref isc::dhcp::Dhcpv4Srv::classSpecificProcessing. Should any need for such a code arise,
+@ref isc::dhcp::Dhcpv4Srv::vendorClassSpecificProcessing. Should any need for such a code arise,
 it will be conducted in an external hooks library.
 
 It is possible to define class restrictions in subnet, so a given subnet is only
diff --git a/src/bin/dhcp6/dhcp6_srv.h b/src/bin/dhcp6/dhcp6_srv.h
index 99ee971f53..c57e61da12 100644
--- a/src/bin/dhcp6/dhcp6_srv.h
+++ b/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. 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).
@@ -678,7 +678,7 @@ protected:
     ///
     /// @param decline Decline messege sent by a client
     /// @param reply Server's response (IA_NA with status will be added here)
-    /// @param client context
+    /// @param ctx context
     /// @return true when expected to continue, false when hooks told us to drop
     ///         the packet
     bool declineLeases(const Pkt6Ptr& decline, Pkt6Ptr& reply,
diff --git a/src/lib/asiolink/io_address.h b/src/lib/asiolink/io_address.h
index b6550dc2e4..6bea9a4dd0 100644
--- a/src/lib/asiolink/io_address.h
+++ b/src/lib/asiolink/io_address.h
@@ -246,8 +246,10 @@ public:
     /// @brief Subtracts one address from another (a - b)
     ///
     /// Treats addresses as integers and subtracts them. For example:
+    /// @code
     /// 192.0.2.5 - 192.0.2.0 = 0.0.0.5
     /// fe80::abcd - fe80:: = ::abcd
+    /// @endcode
     ///
     /// It is possible to subtract greater from lesser address, e.g.
     /// 192.168.56.10 - 192.168.67.20, but please do understand that
diff --git a/src/lib/dhcpsrv/alloc_engine.h b/src/lib/dhcpsrv/alloc_engine.h
index 303a890529..421ac7b3fa 100644
--- a/src/lib/dhcpsrv/alloc_engine.h
+++ b/src/lib/dhcpsrv/alloc_engine.h
@@ -397,7 +397,7 @@ public:
     /// response to SOLICIT).
     ///
     /// This method uses host reservation if ctx.host_ is set. The easy way to
-    /// set it is to call @ref isc::dhcp::AllocEngine::findReservation(ctx).
+    /// set it is to call @ref isc::dhcp::AllocEngine::findReservation(ClientContext6& ctx).
     /// The host reservation is convenient, but incurs performance penalty,
     /// so it can be tweaked on a per subnet basis. There are three possible modes:
     /// 1. disabled (no host reservation at all). This is the most performant one
@@ -524,9 +524,9 @@ public:
     /// declined state). Therefore remove_leases parameter is ignored for
     /// declined leases. They are always removed.
     ///
-    /// Also, for declined leases @ref reclaimDeclined is called. It conducts
-    /// several declined specific operation (extra log entry, stats dump,
-    /// hooks).
+    /// Also, for declined leases @ref reclaimDeclined(const Lease6Ptr&) is
+    /// called. It conducts several declined specific operation (extra log
+    /// entry, stats dump, hooks).
     ///
     /// @param max_leases Maximum number of leases to be reclaimed.
     /// @param timeout Maximum amount of time that the reclaimation routine
@@ -582,9 +582,9 @@ public:
     /// declined state). Therefore remove_leases parameter is ignored for
     /// declined leases. They are always removed.
     ///
-    /// Also, for declined leases @ref reclaimDeclined is called. It conducts
-    /// several declined specific operation (extra log entry, stats dump,
-    /// hooks).
+    /// Also, for declined leases @ref reclaimDeclined(const Lease4Ptr&) is
+    /// called. It conductsseveral declined specific operation (extra log
+    /// entry, stats dump, hooks).
     ///
     /// @param max_leases Maximum number of leases to be reclaimed.
     /// @param timeout Maximum amount of time that the reclaimation routine
diff --git a/src/lib/dhcpsrv/alloc_engine_log.cc b/src/lib/dhcpsrv/alloc_engine_log.cc
index 58a024a8d8..592c6520ea 100644
--- a/src/lib/dhcpsrv/alloc_engine_log.cc
+++ b/src/lib/dhcpsrv/alloc_engine_log.cc
@@ -12,7 +12,7 @@
 // OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 // PERFORMANCE OF THIS SOFTWARE.
 
-/// @file Defines the logger used by the @c isc::dhcp::HostMgr
+/// @brief Defines the logger used by the @c isc::dhcp::HostMgr
 
 #include "dhcpsrv/alloc_engine_log.h"
 
diff --git a/src/lib/dhcpsrv/alloc_engine_log.h b/src/lib/dhcpsrv/alloc_engine_log.h
index 39bf1a3ca7..ce3e60dd93 100644
--- a/src/lib/dhcpsrv/alloc_engine_log.h
+++ b/src/lib/dhcpsrv/alloc_engine_log.h
@@ -22,7 +22,7 @@ namespace isc {
 namespace dhcp {
 
 //@{
-/// \brief Logging levels for the @c AllocEngine.
+/// @brief Logging levels for the @c AllocEngine.
 ///
 /// Defines the levels used to output debug messages from the @c AllocEngine.
 
@@ -47,7 +47,7 @@ const int ALLOC_ENGINE_DBG_TRACE_DETAIL_DATA = DBGLVL_TRACE_DETAIL_DATA;
 
 //@}
 
-/// @brief Logger for the @c AllocEngine..
+/// @brief Logger for the @c AllocEngine.
 ///
 /// Define the logger used to log messages in @c AllocEngine.
 extern isc::log::Logger alloc_engine_logger;
diff --git a/src/lib/dhcpsrv/client_class_def.h b/src/lib/dhcpsrv/client_class_def.h
index 843320c1d1..819bdf6ed7 100644
--- a/src/lib/dhcpsrv/client_class_def.h
+++ b/src/lib/dhcpsrv/client_class_def.h
@@ -83,7 +83,7 @@ public:
 
     /// @brief Sets the class's option collection
     ///
-    /// @param options the option collection to assign the class
+    /// @param cfg_option the option collection to assign the class
     void setCfgOption(const CfgOptionPtr& cfg_option);
 
     /// @brief Compares two @c ClientClassDef objects for equality.
diff --git a/src/lib/dhcpsrv/hosts_log.cc b/src/lib/dhcpsrv/hosts_log.cc
index d9dc1b6847..6fb7ef8da5 100644
--- a/src/lib/dhcpsrv/hosts_log.cc
+++ b/src/lib/dhcpsrv/hosts_log.cc
@@ -12,7 +12,7 @@
 // OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 // PERFORMANCE OF THIS SOFTWARE.
 
-/// @file Defines the logger used by the @c isc::dhcp::HostMgr
+/// @brief Defines the logger used by the @c isc::dhcp::HostMgr
 
 #include "dhcpsrv/hosts_log.h"
 
diff --git a/src/lib/dhcpsrv/parsers/client_class_def_parser.h b/src/lib/dhcpsrv/parsers/client_class_def_parser.h
index 08ed582cb0..3bb206df3e 100644
--- a/src/lib/dhcpsrv/parsers/client_class_def_parser.h
+++ b/src/lib/dhcpsrv/parsers/client_class_def_parser.h
@@ -46,7 +46,7 @@
 ///
 /// -# "option-data" - a list which defines the options that should be
 /// assigned to memebers of the class.  This element is optional and parsed
-/// using the @ref dhcp::OptionDataListParser.
+/// using the @ref isc::dhcp::OptionDataListParser.
 ///
 /// ExpressionParser  - creates an eval::Expression from a string element,
 /// using the Eval Parser.
@@ -171,7 +171,7 @@ public:
     /// @param class_def_list pointer to an element that holds entries
     /// for client class definitions.
     /// @throw DhcpConfigError if configuration parsing fails.
-    void build(isc::data::ConstElementPtr option_def_list);
+    void build(isc::data::ConstElementPtr class_def_list);
 
     /// @brief Commits class definitions to CfgMgr's global storage.
     void commit();
diff --git a/src/lib/dhcpsrv/parsers/dhcp_parsers.h b/src/lib/dhcpsrv/parsers/dhcp_parsers.h
index 63cd98582a..98071bef72 100644
--- a/src/lib/dhcpsrv/parsers/dhcp_parsers.h
+++ b/src/lib/dhcpsrv/parsers/dhcp_parsers.h
@@ -1083,7 +1083,6 @@ protected:
     ///
     /// @throw BadValue if the text cannot be converted.
     ///
-    /// @param text representation for conversion
     /// @return one of allowed HRMode values
     static Subnet::HRMode hrModeFromText(const std::string& txt);
 
diff --git a/src/lib/dns/rdataclass.h b/src/lib/dns/rdataclass.h
index fe49cd94b5..ab55a404a0 100644
--- a/src/lib/dns/rdataclass.h
+++ b/src/lib/dns/rdataclass.h
@@ -408,7 +408,7 @@ class CAA : public Rdata {
 public:
     // BEGIN_COMMON_MEMBERS
 
-    explicit CAA(const std::string& type_str);
+    explicit CAA(const std::string& caa_str);
     CAA(isc::util::InputBuffer& buffer, size_t rdata_len);
     CAA(const CAA& other);
     CAA(
@@ -2304,7 +2304,7 @@ class TLSA : public Rdata {
 public:
     // BEGIN_COMMON_MEMBERS
 
-    explicit TLSA(const std::string& type_str);
+    explicit TLSA(const std::string& tlsa_str);
     TLSA(isc::util::InputBuffer& buffer, size_t rdata_len);
     TLSA(const TLSA& other);
     TLSA(
diff --git a/src/lib/dns/rrclass-placeholder.h b/src/lib/dns/rrclass-placeholder.h
index a7098532b0..a87d28e96e 100644
--- a/src/lib/dns/rrclass-placeholder.h
+++ b/src/lib/dns/rrclass-placeholder.h
@@ -212,7 +212,8 @@ public:
     /// If resource allocation in rendering process fails, a corresponding
     /// standard exception will be thrown.
     ///
-    /// \param buffer An output buffer to store the wire data.
+    /// \param renderer DNS message rendering context that encapsulates the
+    /// output buffer in which the RRClass is to be stored.
     void toWire(AbstractMessageRenderer& renderer) const;
     /// \brief Render the \c RRClass in the wire format.
     ///
@@ -222,8 +223,7 @@ public:
     /// 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 RRClass is to be stored.
+    /// \param buffer An output buffer to store the wire data.
     void toWire(isc::util::OutputBuffer& buffer) const;
     //@}
 
diff --git a/src/lib/dns/rrclass.h b/src/lib/dns/rrclass.h
index f1194e23a2..362d4a700a 100644
--- a/src/lib/dns/rrclass.h
+++ b/src/lib/dns/rrclass.h
@@ -219,7 +219,8 @@ public:
     /// If resource allocation in rendering process fails, a corresponding
     /// standard exception will be thrown.
     ///
-    /// \param buffer An output buffer to store the wire data.
+    /// \param renderer DNS message rendering context that encapsulates the
+    /// output buffer in which the RRClass is to be stored.
     void toWire(AbstractMessageRenderer& renderer) const;
     /// \brief Render the \c RRClass in the wire format.
     ///
@@ -229,8 +230,7 @@ public:
     /// 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 RRClass is to be stored.
+    /// \param buffer An output buffer to store the wire data.
     void toWire(isc::util::OutputBuffer& buffer) const;
     //@}
 
diff --git a/src/lib/dns/rrtype-placeholder.h b/src/lib/dns/rrtype-placeholder.h
index 46167e45dc..180ad55b63 100644
--- a/src/lib/dns/rrtype-placeholder.h
+++ b/src/lib/dns/rrtype-placeholder.h
@@ -185,7 +185,8 @@ public:
     /// If resource allocation in rendering process fails, a corresponding
     /// standard exception will be thrown.
     ///
-    /// \param buffer An output buffer to store the wire data.
+    /// \param renderer DNS message rendering context that encapsulates the
+    /// output buffer in which the RRType is to be stored.
     void toWire(AbstractMessageRenderer& renderer) const;
     /// \brief Render the \c RRType in the wire format.
     ///
@@ -195,8 +196,7 @@ public:
     /// 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 RRType is to be stored.
+    /// \param buffer An output buffer to store the wire data.
     void toWire(isc::util::OutputBuffer& buffer) const;
     //@}
 
diff --git a/src/lib/dns/rrtype.h b/src/lib/dns/rrtype.h
index d2e96be4cd..cbe95e5cf6 100644
--- a/src/lib/dns/rrtype.h
+++ b/src/lib/dns/rrtype.h
@@ -192,7 +192,8 @@ public:
     /// If resource allocation in rendering process fails, a corresponding
     /// standard exception will be thrown.
     ///
-    /// \param buffer An output buffer to store the wire data.
+    /// \param renderer DNS message rendering context that encapsulates the
+    /// output buffer in which the RRType is to be stored.
     void toWire(AbstractMessageRenderer& renderer) const;
     /// \brief Render the \c RRType in the wire format.
     ///
@@ -202,8 +203,7 @@ public:
     /// 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 RRType is to be stored.
+    /// \param buffer An output buffer to store the wire data.
     void toWire(isc::util::OutputBuffer& buffer) const;
     //@}
 
diff --git a/src/lib/dns/tsigkey.h b/src/lib/dns/tsigkey.h
index fe4b4f471d..224aeb8283 100644
--- a/src/lib/dns/tsigkey.h
+++ b/src/lib/dns/tsigkey.h
@@ -114,6 +114,8 @@ public:
     /// \param secret Point to a binary sequence of the shared secret to be
     /// used for this key, or \c NULL if the secret is empty.
     /// \param secret_len The size of the binary %data (\c secret) in bytes.
+    /// \param digestbits The number of bits to include in the digest
+    /// (0 means to include all)
     TSIGKey(const Name& key_name, const Name& algorithm_name,
             const void* secret, size_t secret_len, size_t digestbits = 0);
 
diff --git a/src/lib/util/csv_file.h b/src/lib/util/csv_file.h
index 8549f581cc..a5b57e9387 100644
--- a/src/lib/util/csv_file.h
+++ b/src/lib/util/csv_file.h
@@ -119,7 +119,7 @@ public:
 
     /// @brief Trims a given number of elements from the end of a row
     ///
-    /// @param number of elements to trim
+    /// @param count number of elements to trim
     ///
     /// @throw CSVFileError if the number to trim is larger than
     /// then the number of elements
diff --git a/src/lib/util/versioned_csv_file.h b/src/lib/util/versioned_csv_file.h
index adb780588a..74a6e56ce2 100644
--- a/src/lib/util/versioned_csv_file.h
+++ b/src/lib/util/versioned_csv_file.h
@@ -152,7 +152,7 @@ public:
     /// The name of the column will be placed in the CSV header when new file
     /// is created by calling @c recreate or @c open function.
     ///
-    /// @param name Name of the column.
+    /// @param col_name Name of the column.
     /// @param version  Text representation of the schema version in which
     /// this column first appeared.
     /// @param default_value value the missing column should be given during
@@ -232,7 +232,6 @@ public:
     /// specified by that column's descriptor.
     ///
     /// @param [out] row Object receiving the parsed CSV file.
-    /// @param skip_validation Do not perform validation.
     ///
     /// @return true if row has been read and validated; false if validation
     /// failed.
@@ -255,7 +254,7 @@ public:
     ///
     /// @param index index within the list of columns of the desired column
     /// @return a pointer to the VersionedColumn at the given index
-    /// @trow OutOfRange exception if the index is invalid
+    /// @throw OutOfRange exception if the index is invalid
     const VersionedColumnPtr& getVersionedColumn(const size_t index) const;
 
     /// @brief Fetches the state of the input file's schema
-- 
2.47.3