docs: wrote Doxygen comments for all files

refs: #4118

Change-Id: Ib0e7f1926cdabcca5aa401b59b24519412a099f7

src/adjacent.cpp

@@ -17,15 +17,15 @@
  * You should have received a copy of the GNU General Public License along with
  * NLSR, e.g., in COPYING.md file.  If not, see <http://www.gnu.org/licenses/>.
  **/
+
+#include "adjacent.hpp"
+#include "logger.hpp"
+
 #include <iostream>
 #include <string>
 #include <cmath>
 #include <limits>
 
-
-#include "adjacent.hpp"
-#include "logger.hpp"
-
 namespace nlsr {
 
 INIT_LOGGER("Adjacent");

src/adjacent.hpp

@@ -17,6 +17,7 @@
  * You should have received a copy of the GNU General Public License along with
  * NLSR, e.g., in COPYING.md file.  If not, see <http://www.gnu.org/licenses/>.
  **/
+
 #include <string>
 #include <cmath>
 #include <boost/cstdint.hpp>
@@ -29,6 +30,11 @@
 
 namespace nlsr {
 
+/*! \brief A neighbor reachable over a Face.
+ *
+ * Represents another node that we expect to be running NLSR that we
+ * should be able to reach over a direct Face connection.
+ */
 class Adjacent
 {
 
@@ -120,6 +126,7 @@ public:
     return m_faceId;
   }
 
+  /*! \brief Equality is when name, Face URI, and link cost are all equal. */
   bool
   operator==(const Adjacent& adjacent) const;
 
@@ -148,11 +155,18 @@ public:
   static const float DEFAULT_LINK_COST;
 
 private:
+  /*! m_name The NLSR-configured router name of the neighbor */
   ndn::Name m_name;
+  /*! m_connectingFaceUri The NFD-level specification of the Face*/
   ndn::util::FaceUri m_faceUri;
+  /*! m_linkCost The semi-arbitrary cost to traverse the link. */
   double m_linkCost;
+  /*! m_status Whether the neighbor is active or not */
   Status m_status;
+  /*! m_interestTimedOutNo How many failed Hello interests we have sent since the last reply */
   uint32_t m_interestTimedOutNo;
+  /*! m_faceId The NFD-assigned ID for the neighbor, used to
+   * determine whether a Face is available */
   uint64_t m_faceId;
 };
 

src/common.hpp

@@ -19,6 +19,11 @@
  *
  **/
 
+/*! \file
+ * Shared include file to provide a single point-of-entry, and
+ * hopefully improve compile times.
+ */
+
 #ifndef NLSR_COMMON_HPP
 #define NLSR_COMMON_HPP
 

src/communication/sync-logic-handler.hpp

@@ -22,6 +22,8 @@
 #ifndef NLSR_SYNC_LOGIC_HANDLER_HPP
 #define NLSR_SYNC_LOGIC_HANDLER_HPP
 
+#include "test-access-control.hpp"
+
 #include <ndn-cxx/face.hpp>
 #include <ChronoSync/socket.hpp>
 
@@ -30,8 +32,6 @@
 #include <boost/cstdint.hpp>
 #include <boost/throw_exception.hpp>
 
-#include "test-access-control.hpp"
-
 class InterestManager;
 
 namespace nlsr {
@@ -39,6 +39,14 @@ namespace nlsr {
 class ConfParameter;
 class Lsdb;
 
+/*! \brief NLSR-to-ChronoSync interaction point
+ *
+ * This class serves as the abstraction for the syncing portion of
+ * NLSR and its components. NLSR has no particular reliance on
+ * ChronoSync, except that the NLSR source would need to be modified
+ * for use with other sync protocols.
+ *
+ */
 class SyncLogicHandler
 {
 public:
@@ -54,45 +62,77 @@ public:
 
   SyncLogicHandler(ndn::Face& face, Lsdb& lsdb, ConfParameter& conf);
 
-  /*! \brief Receive and parse update from Sync
-
-    Parses the router name the update came from and passes it to processUpdateFromSync
-
-    \param v The information that Sync has acquired.
+  /*! \brief Hook function to call whenever sync detects new data.
+   *
+   * This function packages the sync information into discrete updates
+   * and passes those off to another function, processUpdateFromSync.
+   * \sa processUpdateFromSync
+   *
+   * \param v A container with the new information sync has received
    */
   void
   onChronoSyncUpdate(const std::vector<chronosync::MissingDataInfo>& v);
 
-  /*! \brief Wrapper function to call publishSyncUpdate with correct LSA type
-
-    \param type The LSA type constant
-    \param seqNo The latest seqNo known to lsdb
+  /*! \brief Instruct ChronoSync to publish an update.
+   *
+   * This function instructs sync to push an update into the network,
+   * based on whatever the state of the sequencing manager is when
+   * this is called. Since each ChronoSync instance maintains its own
+   * PIT, doing this satisfies those interests so that other routers
+   * know a sync update is available.
+   * \sa publishSyncUpdate
    */
   void
   publishRoutingUpdate(const ndn::Name& type, const uint64_t& seqNo);
 
-  /*! \brief Creates ChronoSync socket and register additional sync nodes (user prefixes)
-
-    \param syncPrefix /localhop/NLSR/sync
+  /*! \brief Create and configure a socket to enable ChronoSync for this NLSR.
+   *
+   * In a typical situation this only needs to be called once, when NLSR starts.
+   * \param syncPrefix The sync prefix you want this ChronoSync to use
+   * \sa Nlsr::initialize
    */
   void
   createSyncSocket(const ndn::Name& syncPrefix);
 
 private:
+  /*! \brief Simple function to glue Name components together
+   */
   void
   buildUpdatePrefix();
 
+  /*! \brief Determine which kind of LSA was updated and fetch it.
+   *
+   * Checks that the received update is not from us, which can happen,
+   * and then inspects the update to determine which kind of LSA the
+   * update is for. Finally, it expresses interest for the correct LSA
+   * type.
+   * \throws SyncUpdate::Error If the sync update doesn't look like a sync LSA update.
+   */
   void
   processUpdateFromSync(const ndn::Name& originRouter,
                         const ndn::Name& updateName, const uint64_t& seqNo);
 
+  /*! \brief Consults the LSDB to determine if a sync update has a new LSA.
+   *
+   * Given some information about an LSA, consult the LSDB to
+   * determine if the sequence number represents a new LSA from the
+   * origin router.
+   */
   bool
   isLsaNew(const ndn::Name& originRouter, const std::string& lsaType,
            const uint64_t& seqNo);
 
+  /*! \brief Fetch an LSA of a certain type, with a certain sequence number.
+   */
   void
   expressInterestForLsa(const ndn::Name& updateName, const uint64_t& seqNo);
 
+  /*! \brief Instruct ChronoSync, via the sync socket, to publish an update.
+   *
+   * Each ChronoSync instance maintains its own PIT for sync
+   * updates. This function creates a data that satisfies that update,
+   * so that the interested routers will know new data is available.
+   */
   void
   publishSyncUpdate(const ndn::Name& updatePrefix, uint64_t seqNo);
 
@@ -103,7 +143,7 @@ private:
 
 private:
   Lsdb& m_lsdb;
-  ConfParameter& m_confParam;
+  const ConfParameter& m_confParam;
 
 PUBLIC_WITH_TESTS_ELSE_PRIVATE:
   ndn::Name m_nameLsaUserPrefix;

src/conf-file-processor.cpp

@@ -19,8 +19,8 @@
  * NLSR, e.g., in COPYING.md file.  If not, see <http://www.gnu.org/licenses/>.
  **/
 
-#include "conf-parameter.hpp"
 #include "conf-file-processor.hpp"
+#include "conf-parameter.hpp"
 #include "adjacent.hpp"
 #include "utility/name-helper.hpp"
 #include "update/prefix-update-processor.hpp"

src/conf-file-processor.hpp

@@ -21,14 +21,27 @@
 #ifndef NLSR_CONF_FILE_PROCESSOR_HPP
 #define NLSR_CONF_FILE_PROCESSOR_HPP
 
+#include "nlsr.hpp"
+
 #include <boost/smart_ptr/shared_ptr.hpp>
 #include <boost/property_tree/ptree.hpp>
 #include <boost/cstdint.hpp>
 
-#include "nlsr.hpp"
-
 namespace nlsr {
 
+/*! \brief A class containing methods to parse an NLSR configuration file
+ *
+ * This class contains methods to parse an NLSR configuration file and
+ * set all the parameters in NLSR to the received values. There are
+ * defaults for any unconfigured settings.
+ *
+ * This is currently called by the wrapper class NlsrRunner to
+ * populate the NLSR object with its configuration before NLSR is
+ * started.
+ *
+ * \sa nlsr::ConfParameter
+ * \sa NlsrRunner::run
+ */
 class ConfFileProcessor
 {
 public:
@@ -38,38 +51,80 @@ public:
   {
   }
 
+  /*! \brief Load and parse the configuration file, then populate NLSR.
+   *
+   * Entry-point function that chains all the necessary steps together
+   * to configure an NLSR object.
+   *
+   * \return A boolean for whether configuration was successful.
+   */
   bool
   processConfFile();
 
 private:
   typedef boost::property_tree::ptree ConfigSection;
 
+  /*! \brief Parse the configuration file into a tree and process the nodes.
+   *
+   * Reads the configuration file as a property tree, and then iterates
+   * over them, attempting to parse each node. The nodes themselves
+   * are passed to another function that determines what kind of
+   * section it is and handles it appropriately. On any error in
+   * reading the file, return false.
+   *
+   * \return Whether configuration was successful.
+   */
   bool
   load(std::istream& input);
 
+  /*! \brief A dispatcher-like function to send configuration tree nodes to the right subfunction.
+   */
   bool
   processSection(const std::string& sectionName, const ConfigSection& section);
 
+  /*! \brief Parse general options, including router name, logging directory, LSA refresh.
+   */
   bool
   processConfSectionGeneral(const ConfigSection& section);
 
+  /*! \brief Configure options relating to neighbor configuration and detection.
+   *
+   * Parse options that control NLSR's behavior about neighbors. Such
+   * things include how many hello interests are sent and what their
+   * timeout is, as well as parsing neighbor specifications. Neighbor
+   * Face URIs are parsed and confirmed as valid here by ndn-cxx.
+   */
   bool
   processConfSectionNeighbors(const ConfigSection& section);
 
+  /*! \brief Set the state of hyperbolic routing: off, on, dry-run.
+   */
   bool
   processConfSectionHyperbolic(const ConfigSection& section);
 
+  /*! \brief Set options for the FIB: nexthops per prefix, routing calculation interval.
+   */
   bool
   processConfSectionFib(const ConfigSection& section);
 
+  /*! \brief Set prefixes that NLSR is supposed to advertise immediately.
+   */
   bool
   processConfSectionAdvertising(const ConfigSection& section);
 
+  /*! \brief Parse and set rules for the validator.
+   *
+   * This section parses and sets rules for the validators, which
+   * control what criteria Interest and Data need to follow to be
+   * considered valid by this NLSR.
+   */
   bool
   processConfSectionSecurity(const ConfigSection& section);
 
 private:
+  /*! m_confFileName The full path of the configuration file to parse. */
   std::string m_confFileName;
+  /*! m_nlsr The NLSR object to configure upon successful parsing. */
   Nlsr& m_nlsr;
 };
 

src/conf-parameter.hpp

@@ -106,6 +106,17 @@ enum HyperbolicState {
   HYPERBOLIC_STATE_DEFAULT = 0
 };
 
+/*! \brief A class to house all the configuration parameters for NLSR.
+ *
+ * This class is conceptually a singleton (but not mechanically) which
+ * is just a collection of attributes that serve as a
+ * separation-of-data for NLSR's configuration variables. NLSR refers
+ * to an instance of this class for all its configuration
+ * parameters. This object is typically populated by a
+ * ConfFileProcessor reading a configuration file.
+ *
+ * \sa nlsr::ConfFileProcessor
+ */
 class ConfParameter
 {
 
@@ -441,6 +452,8 @@ public:
     return m_log4CxxConfPath;
   }
 
+  /*! \brief Dump the current state of all attributes to the log.
+   */
   void
   writeLog();
 

src/hello-protocol.cpp

@@ -16,8 +16,8 @@
  *
  * You should have received a copy of the GNU General Public License along with
  * NLSR, e.g., in COPYING.md file.  If not, see <http://www.gnu.org/licenses/>.
- *
  **/
+#include "hello-protocol.hpp"
 
 #include "hello-protocol.hpp"
 #include "nlsr.hpp"
@@ -150,7 +150,7 @@ HelloProtocol::processInterestTimedOut(const ndn::Interest& interest)
     m_nlsr.getAdjacencyList().getTimedOutInterestCount(neighbor);
   _LOG_DEBUG("Status: " << status);
   _LOG_DEBUG("Info Interest Timed out: " << infoIntTimedOutCount);
-  if ((infoIntTimedOutCount < m_nlsr.getConfParameter().getInterestRetryNumber())) {
+  if (infoIntTimedOutCount < m_nlsr.getConfParameter().getInterestRetryNumber()) {
     // interest name: /<neighbor>/NLSR/INFO/<router>
     ndn::Name interestName(neighbor);
     interestName.append(NLSR_COMPONENT);
@@ -188,11 +188,6 @@ HelloProtocol::onContent(const ndn::Interest& interest, const ndn::Data& data)
                                            this, _1, _2));
 }
 
-  // A validator is called on the incoming data, and if the data
-  // passes the validator's description/definitions, this function is
-  // called. Set the neighbor's status to active and refresh its
-  // LSA. If there was a change in status, we schedule an adjacency
-  // LSA build.
 void
 HelloProtocol::onContentValidated(const std::shared_ptr<const ndn::Data>& data)
 {
@@ -223,8 +218,6 @@ HelloProtocol::onContentValidated(const std::shared_ptr<const ndn::Data>& data)
   hpIncrementSignal(Statistics::PacketType::RCV_HELLO_DATA);
 }
 
-  // Simply logs a debug message that the content could not be
-  // validated (and is implicitly being discarded as a result).
 void
 HelloProtocol::onContentValidationFailed(const std::shared_ptr<const ndn::Data>& data,
                                          const std::string& msg)

src/hello-protocol.hpp

@@ -44,53 +44,60 @@ public:
   {
   }
 
-  /*! \brief Schedules a hello Interest event.
-
-    \param seconds The number of seconds to wait before calling the event.
+  /*! \brief Schedules a Hello Interest event.
+   *
+   * This function serves as the Hello Interest loop, and must be
+   * explicitly called to start the Hello cycle. This is done at
+   * NLSR's initialization.
+   *
+   * \sa Nlsr::initialize
+   * \param seconds The number of seconds to wait before calling the event.
    */
   void
   scheduleInterest(uint32_t seconds);
 
-  /*! \brief Sends a hello Interest packet.
-
-    \param interestNamePrefix The name of the router that has published the
-    update we want.  Here that should be: \<router name\>/NLSR/INFO
-
-    \param seconds The lifetime of the Interest we construct, in seconds
-
-    This function attempts to contact neighboring routers to
-    determine their status (which currently is one of: ACTIVE,
-    INACTIVE, or UNKNOWN)
+  /*! \brief Sends a Hello Interest packet.
+   *
+   * \param interestNamePrefix The name of the router that has published the
+   * update we want. Here that should be: \<router name\>/NLSR/INFO
+   *
+   * \param seconds The lifetime of the Interest we construct, in seconds
+   *
+   * This function attempts to contact neighboring routers to
+   * determine their status (which currently is one of: ACTIVE,
+   * INACTIVE, or UNKNOWN)
    */
   void
   expressInterest(const ndn::Name& interestNamePrefix, uint32_t seconds);
 
-  /*! \brief Sends a hello Interest packet that was previously scheduled.
-
-    \param seconds (ignored)
-
-    This function is called as part of a schedule to regularly
-    determine the adjacency status of neighbors. This function checks
-    if the specified neighbor has a Face, and if not creates one. If
-    the neighbor had a Face, it calls \c expressInterest, else it will
-    attempt to create a Face, which will itself attempt to contact the
-    neighbor. Then the function schedules for this function to be invoked again.
+  /*! \brief Sends Hello Interests to all neighbors
+   *
+   * \param seconds (ignored)
+   *
+   * This function is called as part of a schedule to regularly
+   * determine the adjacency status of neighbors. This function
+   * creates and sends a Hello Interest to each neighbor in
+   * Nlsr::m_adjacencyList. If the neighbor has not been contacted
+   * before and curerntly has no Face in NFD, this method will call a
+   * different pipeline that creates the Face first, then registers
+   * prefixes.
    */
   void
   sendScheduledInterest(uint32_t seconds);
 
-  /*! \brief Processes a hello Interest from a neighbor.
-
-    \param name (ignored)
-
-    \param interest The Interest object that we have received and need to
-    process.
-
-    Processes a hello Interest that this router receives from one of
-    its neighbors. If the neighbor that sent the Interest does not
-    have a Face, NLSR will attempt to register one. Also, if the
-    neighbor that sent the Interest was previously marked as INACTIVE,
-    NLSR will attempt to contact it with its own hello Interest.
+  /*! \brief Processes a Hello Interest from a neighbor.
+   *
+   * \param name (ignored)
+   *
+   * \param interest The Interest object that we have received and need to
+   * process.
+   *
+   * Processes a Hello Interest that this router receives from one of
+   * its neighbors. If the neighbor that sent the Interest does not
+   * have a Face, NLSR will attempt to create one. Also, if the
+   * neighbor that sent the Interest was previously marked as
+   * INACTIVE, NLSR will attempt to contact it with its own Hello
+   * Interest.
    */
   void
   processInterest(const ndn::Name& name, const ndn::Interest& interest);
@@ -98,29 +105,75 @@ public:
   ndn::util::signal::Signal<HelloProtocol, Statistics::PacketType> hpIncrementSignal;
 
 private:
+  /*! \brief Try to contact a neighbor via Hello protocol again
+   *
+   * This function will re-send Hello Interests a configured number
+   * of times. After that many failures, HelloProtocol will mark the neighbor as
+   * inactive and will not attempt to contact them until the next time
+   * HelloProtocol::sendScheduledInterest is called.
+   *
+   * \sa nlsr::ConfParameter::getInterestRetryNumber
+   */
   void
   processInterestTimedOut(const ndn::Interest& interest);
 
+  /*! \brief Verify signatures and validate incoming Hello data.
+   */
   void
   onContent(const ndn::Interest& interest, const ndn::Data& data);
 
 PUBLIC_WITH_TESTS_ELSE_PRIVATE:
+
+  /*! \brief Change a neighbor's status
+   *
+   * Whenever incoming Hello data is verified and validated, change
+   * the status of this neighbor and then schedule an adjacency LSA
+   * build for us. This also resets the number of times we've failed
+   * to contact this neighbor so that we will retry later.
+   */
   void
   onContentValidated(const std::shared_ptr<const ndn::Data>& data);
 
 private:
+  /*! \brief Log that incoming data couldn't be validated, but do nothing else.
+   */
   void
   onContentValidationFailed(const std::shared_ptr<const ndn::Data>& data,
                             const std::string& msg);
 
+  /*! \brief Treat a failed Face registration as an INACTIVE neighbor.
+   *
+   * If NLSR fails to register a Face when contacting a neighbor, it
+   * will instantly toggle that neighbor to INACTIVE. This is
+   * necessary because NLSR will put off building its own adjacency
+   * LSA until the status of each neighbor is definitively
+   * known. Without this, NLSR might have to wait many scheduled Hello
+   * intervals to finish building an adjacency LSA.
+   */
   void
   onRegistrationFailure(const ndn::nfd::ControlResponse& response,
                         const ndn::Name& name);
 
+  /*! \brief Set up a Face for NLSR use.
+   *
+   * When NLSR receives a Hello Interest from a neighbor that it has
+   * not seen before, it may need to create a Face for that
+   * neighbor. After doing so, it will be necessary to inform NFD
+   * about the standard prefixes that NLSR needs a node to have in
+   * order to conduct normal operations. This function accomplishes
+   * that, and then sends its own Hello Interest to confirm the
+   * contact.
+   */
   void
   onRegistrationSuccess(const ndn::nfd::ControlParameters& commandSuccessResult,
                         const ndn::Name& neighbor, const ndn::time::milliseconds& timeout);
 
+  /*! \brief Create a Face for an adjacency
+   * \sa HelloProtocol::onRegistrationSuccess
+   */
+  void
+  registerPrefixes(const ndn::Name& adjName, const std::string& faceUri,
+                   double linkCost, const ndn::time::milliseconds& timeout);
 private:
   Nlsr& m_nlsr;
   ndn::Scheduler& m_scheduler;

src/logger.cpp

@@ -16,10 +16,10 @@
  *
  * You should have received a copy of the GNU General Public License along with
  * NLSR, e.g., in COPYING.md file.  If not, see <http://www.gnu.org/licenses/>.
- *
- * \author A K M Mahmudul Hoque <ahoque1@memphis.edu>
- *
  **/
+
+#include "logger.hpp"
+
 #include <log4cxx/logger.h>
 #include <log4cxx/basicconfigurator.h>
 #include <log4cxx/xml/domconfigurator.h>
@@ -32,8 +32,6 @@
 #include <boost/algorithm/string.hpp>
 #include <boost/filesystem.hpp>
 
-#include "logger.hpp"
-
 void
 INIT_LOG4CXX(const std::string& log4cxxConfPath)
 {

src/logger.hpp

@@ -16,11 +16,17 @@
  *
  * You should have received a copy of the GNU General Public License along with
  * NLSR, e.g., in COPYING.md file.  If not, see <http://www.gnu.org/licenses/>.
- *
- * \author A K M Mahmudul Hoque <ahoque1@memphis.edu>
- *
  **/
 
+/*! \file logger.hpp
+ * \brief Define macros and auxiliary functions for logging.
+ *
+ * This file defines the macros that NLSR uses for logging
+ * messages. An intrepid hacker could replace this system cleanly by
+ * providing a system that redefines all of the _LOG_* macros with an
+ * arbitrary system, as long as the underlying system accepts strings.
+ */
+
 #ifndef NLSR_LOGGER_HPP
 #define NLSR_LOGGER_HPP
 

src/nlsr-runner.hpp

@@ -32,6 +32,15 @@
 
 namespace nlsr {
 
+/*! \brief A wrapper class to instantiate and configure an NLSR object.
+ *
+ * As its name suggests, this class is responsible for running
+ * NLSR. It creates an nlsr::ConfFileProcessor to read a configuration
+ * file and uses that to configure and then start an NLSR process. It
+ * also initializes loggers and optionally daemonizes the NLSR
+ * process. This class only exists to provide this functionality, and
+ * there is no special reliance of NLSR on this class.
+ */
 class NlsrRunner
 {
 public:
@@ -47,6 +56,18 @@ public:
 
   NlsrRunner(std::string& configFileName, bool isDaemonProcess);
 
+  /*! \brief Instantiate, configure, and start the NLSR process.
+   *
+   * Each NlsrRunner is uniquely paired to the Face it's instantiated
+   * with. This is *not* a factory-type class, but a one-to-one
+   * relationship. If one wants to create multiple NLSR classes,
+   * multiple NLSR runners need to be created, too.
+   *
+   * \throws Error If the configuration file cannot be processed. NLSR
+   * is not started.
+   *
+   * \sa Nlsr::canonizeNeighborUris
+   */
   void
   run();
 

src/nlsr.hpp

@@ -40,7 +40,9 @@
 #include "utility/name-helper.hpp"
 #include "stats-collector.hpp"
 
+#include <boost/cstdint.hpp>
 #include <stdexcept>
+#include <boost/throw_exception.hpp>
 
 #include <ndn-cxx/face.hpp>
 #include <ndn-cxx/security/key-chain.hpp>
@@ -53,9 +55,6 @@
 #include <ndn-cxx/data.hpp>
 #include <ndn-cxx/encoding/block.hpp>
 
-#include <boost/cstdint.hpp>
-#include <boost/throw_exception.hpp>
-
 namespace nlsr {
 
 static ndn::Name DEFAULT_BROADCAST_PREFIX("/ndn/broadcast");
@@ -292,12 +291,24 @@ public:
     return m_validator;
   }
 
+  /*! \brief Add a certificate NLSR claims to be authoritative for to the certificate store.
+   *
+   * \sa CertificateStore
+   */
   void
   loadCertToPublish(std::shared_ptr<ndn::IdentityCertificate> certificate)
   {
     m_certStore.insert(certificate);
   }
 
+  /*! \brief Find a certificate
+   *
+   * Find a certificate that NLSR has. First it checks against the
+   * certificates this NLSR claims to be authoritative for, usually
+   * something like this specific router's certificate, and then
+   * checks the cache of certficates it has already fetched. If none
+   * can be found, it will return an empty pointer.
+   */
   std::shared_ptr<const ndn::IdentityCertificate>
   getCertificate(const ndn::Name& certificateNameWithoutVersion)
   {
@@ -399,18 +410,28 @@ PUBLIC_WITH_TESTS_ELSE_PRIVATE:
   }
 
 private:
+  /*! \brief Registers the prefix that NLSR will use for key/certificate interests.
+   */
   void
   registerKeyPrefix();
 
+  /*! \brief Registers the prefix that NLSR will consider to be the machine-local, secure prefix.
+   */
   void
   registerLocalhostPrefix();
 
+  /*! \brief Attempts to satisfy an Interest for a certificate, and send it back.
+   */
   void
   onKeyInterest(const ndn::Name& name, const ndn::Interest& interest);
 
+  /*! \brief Do nothing.
+   */
   void
   onKeyPrefixRegSuccess(const ndn::Name& name);
 
+  /*! \brief Do nothing.
+   */
   void
   onFaceEventNotification(const ndn::nfd::FaceEventNotification& faceEventNotification);
 
@@ -463,7 +484,13 @@ PUBLIC_WITH_TESTS_ELSE_PRIVATE:
   HelloProtocol m_helloProtocol;
 
 private:
+  /*! \brief Where NLSR caches certificates it has fetched to validate
+   * Data signatures.
+   */
   std::shared_ptr<ndn::CertificateCacheTtl> m_certificateCache;
+  /*! \brief Where NLSR stores certificates it claims to be
+   * authoritative for. Usually the router certificate.
+   */
   security::CertificateStore m_certStore;
 
 PUBLIC_WITH_TESTS_ELSE_PRIVATE:

src/publisher/lsa-publisher.hpp

@@ -44,7 +44,9 @@ public:
                         ndn::Face& face,
                         ndn::KeyChain& keyChain);
 
-  /*! \brief Returns the adj. LSAs represented by this object. */
+  /*! \brief Generates an TLV-format AdjacencyLsa from AdjacencyLsas
+   * and their Adjacents.
+   */
   std::list<tlv::AdjacencyLsa>
   getTlvLsas();
 
@@ -65,7 +67,9 @@ public:
                         ndn::Face& face,
                         ndn::KeyChain& keyChain);
 
-  /*! \brief Returns the cor. LSAs represented by this object. */
+  /*! \brief Generates a TLV-format CoordinateLsa from CoordinateLsas
+   * and their hyperbolic coordinates.
+   */
   std::list<tlv::CoordinateLsa>
   getTlvLsas();
 
@@ -85,7 +89,10 @@ public:
   NameLsaPublisher(Lsdb& lsdb,
                    ndn::Face& face,
                    ndn::KeyChain& keyChain);
-  /*! \brief Returns the name LSAs represented by this object. */
+
+  /*! \brief Generates a TLV-format NameLsa from NameLsas and their
+   * list of name prefixes.
+   */
   std::list<tlv::NameLsa>
   getTlvLsas();
 

src/publisher/lsdb-dataset-interest-handler.hpp

@@ -69,7 +69,8 @@ public:
   }
 
 private:
-  /*! \brief set dispatcher for localhost/router name.
+  /*! \brief Capture-point for Interests to verify Interests are
+   * valid, and then process them.
    */
   void
   setDispatcher(ndn::mgmt::Dispatcher& dispatcher);

src/publisher/segment-publisher.hpp

@@ -52,6 +52,8 @@ public:
   {
   }
 
+  /*! \brief Define the max segment size as half the max NDN packet size.
+   */
   static size_t
   getMaxSegmentSize()
   {
@@ -65,7 +67,12 @@ public:
     return ndn::time::milliseconds(1000);
   }
 
-  /*! \brief Publish data under provided prefix
+  /*! \brief Publish data under the provided prefix
+   *
+   * Processes whatever is provided from SegmentPublisher::generate,
+   * by breaking it into segments of MAX_SEGMENT_SIZE and sending each
+   * one individually. The last segment is distinguished by having the
+   * final block ID set to a timestamp.
    */
   void
   publish(const ndn::Name& prefix,
@@ -112,6 +119,8 @@ protected:
   generate(ndn::EncodingBuffer& outBuffer) = 0;
 
 private:
+  /*! \brief Helper function to sign and put data on a Face.
+   */
   void
   publishSegment(std::shared_ptr<ndn::Data>& data, const ndn::security::SigningInfo& signingInfo)
   {

src/route/fib.cpp

@@ -48,6 +48,7 @@ Fib::remove(const ndn::Name& name)
            (it->second).getNexthopList().getNextHops().begin();
          nhit != (it->second).getNexthopList().getNextHops().end(); nhit++) {
       //remove entry from NDN-FIB
+      // Only unregister the prefix if it ISN'T a neighbor.
       if (isPrefixUpdatable((it->second).getName())) {
         unregisterPrefix((it->second).getName(), nhit->getConnectingFaceUri());
       }

src/route/fib.hpp

@@ -38,6 +38,19 @@ class AdjacencyList;
 class ConfParameter;
 class FibEntry;
 
+/*! \brief Maps names to lists of next hops, and exports this information to NFD.
+ *
+ * The FIB (Forwarding Information Base) is the "authoritative" source
+ * of how to route Interests on this router to other nodes running
+ * NLSR. In essence, the FIB is a map that takes name prefixes to a
+ * list of next-hops out of this router. This class also contains
+ * methods to inform NFD about these relationships. The FIB has its
+ * entries populated by the NamePrefixTable
+ *
+ * \sa nlsr::NamePrefixTable
+ * \sa nlsr::NamePrefixTable::addEntry
+ * \sa nlsr::NamePrefixTable::updateWithNewRoute
+ */
 class Fib
 {
 public:
@@ -51,15 +64,42 @@ public:
   {
   }
 
-  FibEntry*
-  processUpdate(const ndn::Name& name, NexthopList& allHops);
-
+  /*! \brief Completely remove a name prefix from the FIB.
+   *
+   * If a name prefix is found to no longer be reachable from this
+   * router, it will be removed from the FIB and all of its next-hops
+   * will be unregistered from NFD.
+   *
+   * \sa nlsr::NamePrefixTable::removeEntry
+   */
   VIRTUAL_WITH_TESTS void
   remove(const ndn::Name& name);
 
+  /*! \brief Set the nexthop list of a name.
+   *
+   * This method is the entry for others to add next-hop information
+   * to the FIB. Formally put, this method registers in NFD all
+   * next-hops in allHops, and unregisters the set difference of
+   * newHops - oldHops. This method also schedules the regular refresh
+   * of those next hops.
+   *
+   * \param name The name prefix that the next-hops apply to
+   * \param allHops A complete list of next-hops to associate with name.
+   */
   VIRTUAL_WITH_TESTS void
   update(const ndn::Name& name, NexthopList& allHops);
 
+  /*! \brief Remove all entries from the FIB.
+   *
+   * This method is called before terminating NLSR to minimize the
+   * time NFD spends routing on now-invalid information. This is not
+   * strictly necessary, because eventually those prefix registrations
+   * will expire, but cleaning up after ourselves improves
+   * performance.
+   *
+   * \sa NlsrRunner::run
+   *
+   */
   void
   clean();
 
@@ -69,6 +109,26 @@ public:
     m_refreshTime = fert;
   }
 
+  /*! \brief Inform NFD of a next-hop
+   *
+   * This method informs NFD of a next-hop for some name prefix. This
+   * method actually submits the information to NFD's RIB, which then
+   * aggregates its own best hops and updates NFD's (the actual)
+   * FIB. Typically, NLSR's FIB and NFD's FIB will be almost the
+   * same. However, this is not necessarily the case and there may be
+   * cases when other sources of information provide better next-hops
+   * to NFD that NLSR doesn't know about. For example, an operator
+   * could set up a direct link to a node that isn't running NLSR.
+   *
+   * \param namePrefix The name prefix to register a next-hop for
+   * \param faceUri The faceUri of the adjacent that this prefix can be reached through
+   * \param faceCost The cost to reach namePrefix through faceUri
+   * \param timeout How long this registration should last
+   * \param flags Route inheritance flags (CAPTURE, CHILD_INHERIT)
+   * \param times How many times we have failed to register this prefix since the last success.
+   *
+   * \sa Fib::registerPrefixInNfd
+   */
   void
   registerPrefix(const ndn::Name& namePrefix,
                  const ndn::util::FaceUri& faceUri,
@@ -84,22 +144,39 @@ public:
   writeLog();
 
 private:
+  /*! \brief Indicates whether a prefix is a direct neighbor or not.
+   *
+   * \return Whether the name is NOT associated with a direct neighbor
+   */
   bool
   isPrefixUpdatable(const ndn::Name& name);
 
+  /*! \brief Does one half of the updating of a FibEntry with new next-hops.
+   *
+   * Adds nexthops to a FibEntry and registers them in NFD.
+   * \sa Fib::update
+   * \sa Fib::removeOldNextHopsFromFibEntryAndNfd
+   */
   void
   addNextHopsToFibEntryAndNfd(FibEntry& entry, NexthopList& hopsToAdd);
 
   unsigned int
   getNumberOfFacesForName(NexthopList& nextHopList);
 
+  /*! \brief Unregisters a prefix from NFD's RIB.
+   *
+   */
   void
   unregisterPrefix(const ndn::Name& namePrefix, const std::string& faceUri);
 
+  /*! \brief Log registration success, and update the Face ID associated with a URI.
+   */
   void
   onRegistrationSuccess(const ndn::nfd::ControlParameters& commandSuccessResult,
                         const std::string& message, const ndn::util::FaceUri& faceUri);
 
+  /*! \brief Retry a prefix (next-hop) registration up to three (3) times.
+   */
   void
   onRegistrationFailure(const ndn::nfd::ControlResponse& response,
                         const std::string& message,
@@ -107,18 +184,26 @@ private:
                         const ndn::util::FaceUri& faceUri,
                         uint8_t times);
 
+  /*! \brief Log a successful unregistration.
+   */
   void
   onUnregistrationSuccess(const ndn::nfd::ControlParameters& commandSuccessResult,
                           const std::string& message);
 
+  /*! \brief Log an unregistration failure. Does not retry.
+   */
   void
   onUnregistrationFailure(const ndn::nfd::ControlResponse& response,
                                const std::string& message);
 
+  /*! \brief Log a successful strategy setting.
+   */
   void
   onSetStrategySuccess(const ndn::nfd::ControlParameters& commandSuccessResult,
                        const std::string& message);
 
+  /*! \brief Retry a strategy setting up to three (3) times.
+   */
   void
   onSetStrategyFailure(const ndn::nfd::ControlResponse& response,
                        const ndn::nfd::ControlParameters& parameters,
@@ -126,16 +211,45 @@ private:
                        const std::string& message);
 
 PUBLIC_WITH_TESTS_ELSE_PRIVATE:
+  /*! \brief Internal portion of Fib::update.
+   * \sa Fib::update
+   */
+  FibEntry*
+  processUpdate(const ndn::Name& name, NexthopList& allHops);
+
+  /*! \brief Schedule a refresh event for an entry.
+   *
+   * Schedules a refresh event for an entry. In order to form a
+   * perpetual loop, refreshCallback needs to call
+   * Fib::scheduleEntryRefresh in some way, with refreshCallback being
+   * the same each time. In the current implementation, this is
+   * accomplished by having a separate function, Fib::scheduleLoop,
+   * that does this work.
+   * \sa Fib::scheduleLoop
+   */
   void
   scheduleEntryRefresh(FibEntry& entry, const afterRefreshCallback& refreshCb);
 
 private:
+  /*! \brief Continue the entry refresh cycle.
+   */
   void
   scheduleLoop(FibEntry& entry);
 
+  /*! \brief Cancel an entry's refresh event.
+   *
+   * Cancel an entry's refresh event. This only needs to be done when
+   * an entry is removed. Typically this happens when NLSR is
+   * terminated or crashes, and we don't want the scheduler to crash
+   * because it's referencing memory that has no valid function.
+   *
+   * \sa NlsrRunner::run
+   */
   void
   cancelEntryRefresh(const FibEntry& entry);
 
+  /*! \brief Refreshes an entry in NFD.
+   */
   void
   refreshEntry(const ndn::Name& name, afterRefreshCallback refreshCb);
 
@@ -152,6 +266,10 @@ private:
   AdjacencyList& m_adjacencyList;
   ConfParameter& m_confParameter;
 
+  /*! GRACE_PERIOD A "window" we append to the timeout time to
+   * allow for things like stuttering prefix registrations and
+   * processing time when refreshing events.
+   */
   static const uint64_t GRACE_PERIOD;
 };
 

src/route/map-entry.hpp

@@ -17,9 +17,8 @@
  * You should have received a copy of the GNU General Public License along with
  * NLSR, e.g., in COPYING.md file.  If not, see <http://www.gnu.org/licenses/>.
  *
- * \author A K M Mahmudul Hoque <ahoque1@memphis.edu>
- *
  **/
+
 #ifndef NLSR_MAP_ENTRY_HPP
 #define NLSR_MAP_ENTRY_HPP
 

src/route/name-prefix-table-entry.hpp

@@ -56,6 +56,9 @@ public:
     return m_rteList;
   }
 
+  /*! \brief Resets the next hop lists of all routing table entries
+   * that advertise this name prefix.
+   */
   void
   resetRteListNextHop()
   {
@@ -78,24 +81,25 @@ public:
     return m_nexthopList;
   }
 
-  /*! \brief Generates a next-hop list from routing table entries. */
+  /*! \brief Collect all next-hops that are advertised by this entry's
+   * routing entries.
+   */
   void
   generateNhlfromRteList();
 
   /*! \brief Removes a routing entry from this NPT entry.
-    \param rtpePtr The routing entry
-    \return The remaining number of other NPTs using the removed routing entry.
-  */
+   * \return The number of NPTs using the just-removed routing entry.
+   */
   uint64_t
   removeRoutingTableEntry(std::shared_ptr<RoutingTablePoolEntry> rtpePtr);
 
   /*! \brief Adds a routing entry to this NPT entry.
-    \param rtpePtr The routing entry.
-
-    Adds a routing table pool entry to this NPT entry's list
-    (reminder: each RTPE has a next-hop list). They are used to
-    calculate this entry's overall next-hop list.
-  */
+   * \param rtpePtr The routing entry.
+   *
+   * Adds a routing table pool entry to this NPT entry's list
+   * (reminder: each RTPE has a next-hop list). They are used to
+   * calculate this entry's overall next-hop list.
+   */
   void
   addRoutingTableEntry(std::shared_ptr<RoutingTablePoolEntry> rtpePtr);
 

src/route/nexthop-list.hpp

@@ -17,18 +17,19 @@
  * You should have received a copy of the GNU General Public License along with
  * NLSR, e.g., in COPYING.md file.  If not, see <http://www.gnu.org/licenses/>.
  **/
+
 #ifndef NLSR_NEXTHOP_LIST_HPP
 #define NLSR_NEXTHOP_LIST_HPP
 
+#include "nexthop.hpp"
+#include "adjacent.hpp"
+
 #include <set>
 #include <iostream>
 #include <boost/cstdint.hpp>
 
 #include <ndn-cxx/face.hpp>
 
-#include "nexthop.hpp"
-#include "adjacent.hpp"
-
 namespace nlsr {
 
 struct NextHopComparator {
@@ -144,4 +145,4 @@ operator<<(std::ostream& os, const NexthopList& nhl);
 
 } // namespace nlsr
 
-#endif //NLSR_NEXTHOP_LIST_HPP
+#endif // NLSR_NEXTHOP_LIST_HPP

src/route/routing-table-entry.hpp

@@ -17,15 +17,15 @@
  * You should have received a copy of the GNU General Public License along with
  * NLSR, e.g., in COPYING.md file.  If not, see <http://www.gnu.org/licenses/>.
  *
- * \author A K M Mahmudul Hoque <ahoque1@memphis.edu>
- *
  **/
+
 #ifndef NLSR_ROUTING_TABLE_ENTRY_HPP
 #define NLSR_ROUTING_TABLE_ENTRY_HPP
 
+#include "nexthop-list.hpp"
+
 #include <iostream>
 #include <ndn-cxx/name.hpp>
-#include "nexthop-list.hpp"
 
 namespace nlsr {
 

src/route/routing-table-pool-entry.hpp

@@ -17,19 +17,32 @@
  * You should have received a copy of the GNU General Public License along with
  * NLSR, e.g., in COPYING.md file.  If not, see <http://www.gnu.org/licenses/>.
  *
- * \author Nicholas Gordon <nmgordon@memphis.edu>
- *
  **/
 
 #ifndef NLSR_ROUTING_TABLE_POOL_ENTRY_HPP
 #define NLSR_ROUTING_TABLE_POOL_ENTRY_HPP
 
+#include "routing-table-entry.hpp"
+#include "nexthop-list.hpp"
+
 #include <iostream>
 #include <ndn-cxx/name.hpp>
-#include "nexthop-list.hpp"
-#include "routing-table-entry.hpp"
 
 namespace nlsr {
+
+/*! \brief A deduplication system for the NamePrefixTable
+ *
+ * The NamePrefixTable associates name prefixes to a router. To do
+ * this, it needs to know if certain routers are reachable. This in
+ * turn requires access to entries from the RoutingTable, which are
+ * associated with name prefixes. Doing this naively copies the entry
+ * from the RoutingTable each time, which is costly. This class
+ * provides a deduplication system where the NamePrefixTable can
+ * maintain a collection of RoutingTablePoolEntries. Then, this new
+ * class can be associated with the name prefixes instead of the
+ * original entries, which provides a minimal memory solution.
+ * \sa NamePrefixTable
+ */
 class RoutingTablePoolEntry : public RoutingTableEntry
 {
 public:

src/route/routing-table.hpp

@@ -23,15 +23,15 @@
 #ifndef NLSR_ROUTING_TABLE_HPP
 #define NLSR_ROUTING_TABLE_HPP
 
+#include "conf-parameter.hpp"
+#include "routing-table-entry.hpp"
+
 #include <iostream>
 #include <utility>
 #include <string>
 #include <boost/cstdint.hpp>
 #include <ndn-cxx/util/scheduler.hpp>
 
-#include "conf-parameter.hpp"
-#include "routing-table-entry.hpp"
-
 namespace nlsr {
 
 class Nlsr;
@@ -48,33 +48,34 @@ public:
   }
 
   /*! \brief Calculates a list of next hops for each router in the network.
-    \param pnlsr The NLSR object that contains the LSAs needed for adj. info.
-
-    Calculates the list of next hops to every other router in the network.
-  */
+   * \param pnlsr The NLSR object that contains the LSAs needed for adj. info.
+   *
+   * Calculates the list of next hops to every other router in the network.
+   */
   void
   calculate(Nlsr& pnlsr);
 
   /*! \brief Adds a next hop to a routing table entry.
-    \param destRouter The destination router whose RTE we want to modify.
-    \param nh The next hop to add to the RTE.
-  */
+   * \param destRouter The destination router whose RTE we want to modify.
+   * \param nh The next hop to add to the RTE.
+   */
   void
   addNextHop(const ndn::Name& destRouter, NextHop& nh);
 
   /*! \brief Adds a next hop to a routing table entry in a dry run scenario.
-    \param destRouter The destination router whose RTE we want to modify.
-    \param nh The next hop to add to the router.
-  */
+   * \param destRouter The destination router whose RTE we want to modify.
+   * \param nh The next hop to add to the router.
+   */
   void
   addNextHopToDryTable(const ndn::Name& destRouter, NextHop& nh);
 
   RoutingTableEntry*
   findRoutingTableEntry(const ndn::Name& destRouter);
 
-  /*! \brief Schedules a calculation event in the event scheduler.
-    \param pnlsr The NLSR whose scheduling status is needed.
-  */
+  /*! \brief Schedules a calculation event in the event scheduler only
+   * if one isn't already scheduled.
+   * \param pnlsr The NLSR whose scheduling status is needed.
+   */
   void
   scheduleRoutingTableCalculation(Nlsr& pnlsr);
 
@@ -131,4 +132,4 @@ private:
 
 } // namespace nlsr
 
-#endif //NLSR_ROUTING_TABLE_HPP
+#endif // NLSR_ROUTING_TABLE_HPP

src/security/certificate-store.hpp

@@ -31,6 +31,13 @@
 namespace nlsr {
 namespace security {
 
+/*! \brief Store certificates for names
+ *
+ * Stores certificates that this router claims to be authoritative
+ * for. That is, this stores only the certificates that we will reply
+ * to KEY interests with, e.g. when other routers are verifying data
+ * we have sent.
+ */
 class CertificateStore
 {
 public:

src/tlv/adjacency-lsa.hpp

@@ -43,7 +43,7 @@ namespace tlv {
                      LsaInfo
                      Adjacency*
 
-   \sa http://redmine.named-data.net/projects/nlsr/wiki/LSDB_DataSet
+   \sa https://redmine.named-data.net/projects/nlsr/wiki/LSDB_DataSet
  */
 class AdjacencyLsa
 {
@@ -109,13 +109,33 @@ public:
     return *this;
   }
 
+  /*! \brief Encodes the Adjacent objects and some info using the method in TAG.
+   *
+   * This function will TLV-format the Adjacent objects and some LSA
+   * info using the implementation speciifed by TAG. Usually this is
+   * called with an estimator first to guess how long the buffer needs
+   * to be, then with an encoder to do the real work. This process is
+   * automated by the other wireEncode.
+   * \sa AdjacencyLsa::wireEncode()
+   */
   template<ndn::encoding::Tag TAG>
   size_t
   wireEncode(ndn::EncodingImpl<TAG>& block) const;
 
+  /*! \brief Create a TLV encoding of this object.
+   *
+   * Create a block containing the TLV encoding of this object. That
+   * involves two steps: estimating the size that the information will
+   * take up, and then creating a buffer of that size and encoding the
+   * information into it. Both steps are accomplished by
+   * AdjacencyLsa::wireEncode(ndn::EncodingImpl<TAG>&)
+   */
   const ndn::Block&
   wireEncode() const;
 
+  /*! \brief Populate this object by decoding the one contained in the
+   * given block.
+   */
   void
   wireDecode(const ndn::Block& wire);
 

src/tlv/adjacency.hpp

@@ -39,7 +39,7 @@ namespace tlv {
                   Uri
                   Cost
 
-   \sa http://redmine.named-data.net/projects/nlsr/wiki/LSDB_DataSet
+   \sa https://redmine.named-data.net/projects/nlsr/wiki/LSDB_DataSet
  */
 class Adjacency
 {
@@ -101,13 +101,31 @@ public:
     return *this;
   }
 
+  /*! \brief TLV-encode this object using the implementation in from TAG.
+   *
+   * This method TLV-encodes this Adjacency object using the
+   * implementation given by TAG. Usually two implementations are
+   * provided: a size estimator and a real encoder, which are used in
+   * sequence to allocate the necessary block size and then encode it.
+   * \sa Adjacency::wireEncode()
+   */
   template<ndn::encoding::Tag TAG>
   size_t
   wireEncode(ndn::EncodingImpl<TAG>& block) const;
 
+  /*! \brief Create a TLV encoding of this object.
+   *
+   * This function automates the process of guessing the necessary
+   * size of a block containing this object, and then creating a block
+   * and putting the TLV encoding into it.
+   * \sa Adjacency::wireEncode(ndn::EncodingImpl<TAG>&)
+   */
   const ndn::Block&
   wireEncode() const;
 
+  /*! \brief Populate this object by decoding the object contained in
+   * the given block.
+   */
   void
   wireDecode(const ndn::Block& wire);
 

src/tlv/coordinate-lsa.hpp

@@ -103,13 +103,33 @@ public:
     return *this;
   }
 
+  /*! \brief Encodes the hyperbolic coordinates and some info using the method in TAG.
+   *
+   * This function will TLV-format the hyperbolic coordinates objects and some LSA
+   * info using the implementation speciifed by TAG. Usually this is
+   * called with an estimator first to guess how long the buffer needs
+   * to be, then with an encoder to do the real work. This process is
+   * automated by the other wireEncode.
+   * \sa CoordinateLsa::wireEncode()
+   */
   template<ndn::encoding::Tag TAG>
   size_t
   wireEncode(ndn::EncodingImpl<TAG>& block) const;
 
+  /*! \brief Create a TLV encoding of this object.
+   *
+   * Create a block containing the TLV encoding of this object. That
+   * involves two steps: estimating the size that the information will
+   * take up, and then creating a buffer of that size and encoding the
+   * information into it. Both steps are accomplished by
+   * CoordinateLsa::wireEncode(ndn::EncodingImpl<TAG>&)
+   */
   const ndn::Block&
   wireEncode() const;
 
+  /*! \brief Populate this object by decoding the one contained in the
+   * given block.
+   */
   void
   wireDecode(const ndn::Block& wire);
 

src/tlv/lsa-info.hpp

@@ -22,6 +22,8 @@
 #ifndef NLSR_TLV_LSA_INFO_HPP
 #define NLSR_TLV_LSA_INFO_HPP
 
+#include "lsa.hpp"
+
 #include <ndn-cxx/util/time.hpp>
 #include <ndn-cxx/encoding/block.hpp>
 #include <ndn-cxx/encoding/encoding-buffer.hpp>
@@ -29,8 +31,6 @@
 #include <ndn-cxx/name.hpp>
 #include <boost/throw_exception.hpp>
 
-#include "lsa.hpp"
-
 namespace nlsr {
 namespace tlv {
 
@@ -115,13 +115,33 @@ public:
     return m_hasInfiniteExpirationPeriod;
   }
 
+  /*! \brief Encodes LSA info using the method in TAG.
+   *
+   * This function will TLV-format LSA info using the implementation
+   * speciifed by TAG. Usually this is called with an estimator first
+   * to guess how long the buffer needs to be, then with an encoder to
+   * do the real work. This process is automated by the other
+   * wireEncode.
+   * \sa LsaInfo::wireEncode()
+   */
   template<ndn::encoding::Tag TAG>
   size_t
   wireEncode(ndn::EncodingImpl<TAG>& block) const;
 
+  /*! \brief Create a TLV encoding of this object.
+   *
+   * Create a block containing the TLV encoding of this object. That
+   * involves two steps: estimating the size that the information will
+   * take up, and then creating a buffer of that size and encoding the
+   * information into it. Both steps are accomplished by
+   * LsaInfo::wireEncode(ndn::EncodingImpl<TAG>&)
+   */
   const ndn::Block&
   wireEncode() const;
 
+  /*! \brief Populate this object by decoding the one contained in the
+   * given block.
+   */
   void
   wireDecode(const ndn::Block& wire);
 

src/tlv/lsdb-status.hpp

@@ -45,7 +45,7 @@ namespace tlv {
                    CoordinateLsa*
                    NameLsa*
 
-   \sa http://redmine.named-data.net/projects/nlsr/wiki/LSDB_DataSet
+   \sa https://redmine.named-data.net/projects/nlsr/wiki/LSDB_DataSet
  */
 class LsdbStatus
 {
@@ -156,13 +156,34 @@ public:
     return m_hasNameLsas;
   }
 
+  /*! \brief Encodes the LSA objects and some info for each LSA using
+   * the method in TAG.
+   *
+   * This function will TLV-format the LSA objects and some LSA
+   * info using the implementation specified by TAG. Usually this is
+   * called with an estimator first to guess how long the buffer needs
+   * to be, then with an encoder to do the real work. This process is
+   * automated by the other wireEncode.
+   * \sa LsdbStatus::wireEncode()
+   */
   template<ndn::encoding::Tag TAG>
   size_t
   wireEncode(ndn::EncodingImpl<TAG>& block) const;
 
+  /*! \brief Create a TLV encoding of this object.
+   *
+   * Create a block containing the TLV encoding of this object. That
+   * involves two steps: estimating the size that the information will
+   * take up, and then creating a buffer of that size and encoding the
+   * information into it. Both steps are accomplished by
+   * LsdbStatus::wireEncode(ndn::EncodingImpl<TAG>&)
+   */
   const ndn::Block&
   wireEncode() const;
 
+  /*! \brief Populate this object by decoding the one contained in the
+   * given block.
+   */
   void
   wireDecode(const ndn::Block& wire);
 

src/tlv/name-lsa.hpp

@@ -42,7 +42,7 @@ namespace tlv {
                 LsaInfo
                 Name+
 
-   \sa http://redmine.named-data.net/projects/nlsr/wiki/LSDB_DataSet
+   \sa https://redmine.named-data.net/projects/nlsr/wiki/LSDB_DataSet
  */
 class NameLsa
 {
@@ -108,13 +108,33 @@ public:
     return *this;
   }
 
+  /*! \brief Encodes the Name objects and some info using the method in TAG.
+   *
+   * This function will TLV-format the Name objects and some LSA
+   * info using the implementation speciifed by TAG. Usually this is
+   * called with an estimator first to guess how long the buffer needs
+   * to be, then with an encoder to do the real work. This process is
+   * automated by the other wireEncode.
+   * \sa NameLsa::wireEncode()
+   */
   template<ndn::encoding::Tag TAG>
   size_t
   wireEncode(ndn::EncodingImpl<TAG>& block) const;
 
+  /*! \brief Create a TLV encoding of this object.
+   *
+   * Create a block containing the TLV encoding of this object. That
+   * involves two steps: estimating the size that the information will
+   * take up, and then creating a buffer of that size and encoding the
+   * information into it. Both steps are accomplished by
+   * NameLsa::wireEncode(ndn::EncodingImpl<TAG>&)
+   */
   const ndn::Block&
   wireEncode() const;
 
+  /*! \brief Populate this object by decoding the one contained in the
+   * given block.
+   */
   void
   wireDecode(const ndn::Block& wire);
 

src/tlv/tlv-nlsr.hpp

@@ -24,11 +24,15 @@
 
 #include <ndn-cxx/encoding/tlv.hpp>
 
-namespace ndn  {
-namespace tlv  {
+namespace ndn {
+namespace tlv {
 namespace nlsr {
 
-// LSDB DataSet
+/*! The TLV block types that NLSR uses to encode/decode LSA types. The
+ *  way NLSR encodes LSAs to TLV is by encoding each element of the
+ *  LSA as a separate TLV block. So, block types are needed. These are
+ *  used in the LSDB Status Dataset.
+ */
 enum {
   LsaInfo          = 128,
   OriginRouter     = 129,

src/update/nfd-rib-commands.hpp

@@ -19,6 +19,21 @@
  * NLSR, e.g., in COPYING.md file.  If not, see <http://www.gnu.org/licenses/>.
  **/
 
+/*! \file
+ * Define parameters for NFD RIB commands
+ *
+ * When validating an NFD RIB command, NLSR is only concerned with the
+ * name in the command. However, a request is rejected if it has
+ * unsolicited fields, so the origin, which is set by NFD's RIB, must
+ * be considered optional. We consider these to be secure because they
+ * are currently only received over the localhost prefix. These serve
+ * to support NFD RIB to NLSR route readvertising.
+ *
+ * \sa NfdRibCommandProcessor
+ * \sa nlsr::Nlsr::LOCALHOST_PREFIX
+ * \sa nlsr::Nlsr::getDispatcher
+ */
+
 #ifndef UPDATE_NFD_RIB_COMMANDS_HPP
 #define UPDATE_NFD_RIB_COMMANDS_HPP
 

src/update/prefix-update-commands.hpp

@@ -19,6 +19,18 @@
  * NLSR, e.g., in COPYING.md file.  If not, see <http://www.gnu.org/licenses/>.
  **/
 
+/*! \file
+ * Define parameters for commands to manipulate advertised name prefixes
+ *
+ * These classes serve to define what parameters are required for
+ * Prefix Update commands. We assume these commands are secure because
+ * they are received on the localhost prefix. We require that a name
+ * be present to action upon, and also that our response have a
+ * name. Responses are only sent on failures.
+ *
+ * \sa PrefixUpdateProcessor
+ */
+
 #ifndef NLSR_UPDATE_PREFIX_UPDATE_COMMANDS_HPP
 #define NLSR_UPDATE_PREFIX_UPDATE_COMMANDS_HPP
 

src/update/prefix-update-processor.hpp

@@ -55,6 +55,18 @@ public:
                         ndn::KeyChain& keyChain,
                         std::shared_ptr<ndn::CertificateCacheTtl> certificateCache,
                         security::CertificateStore& certStore);
+
+  /*! \brief Load the validator's configuration from a section of a
+   * configuration file.
+   * \sa ConfFileProcessor::processConfFile
+   * \sa ConfFileProcessor::processConfSectionSecurity
+   *
+   * Loads the state of the validator for prefix update commands by
+   * reading a section from a configuration file. This function is
+   * expecting the section to be from a Boost property tree object.
+   *
+   * \throws PrefixUpdateProcessor::Error If configuration fails to load successfully
+   */
   void
   loadValidator(ConfigSection section, const std::string& filename);