docs: improve Doxygen comments.
refs: #1435
Change-Id: I21624ef4eec393c82a50229a07e8277fb6ae4ddf
diff --git a/src/lsdb.hpp b/src/lsdb.hpp
index 9060ba0..6666558 100644
--- a/src/lsdb.hpp
+++ b/src/lsdb.hpp
@@ -47,19 +47,39 @@
bool
doesLsaExist(const ndn::Name& key, const std::string& lsType);
- // functions related to Name LSDB
+
+ /*! \brief Builds a name LSA for this router and then installs it
+ into the LSDB.
+ */
bool
buildAndInstallOwnNameLsa();
+ /*! \brief Returns the name LSA with the given key.
+ \param key The name of the router that the desired LSA comes from.
+ */
NameLsa*
findNameLsa(const ndn::Name& key);
+ /*! \brief Installs a name LSA into the LSDB
+ \param nlsa The name LSA to install into the LSDB.
+ */
bool
installNameLsa(NameLsa& nlsa);
+ /*! \brief Remove a name LSA from the LSDB.
+ \param key The name of the router that published the LSA to remove.
+
+ This function will remove a name LSA from the LSDB by finding an
+ LSA whose name matches key. This removal also causes the NPT to
+ remove those name prefixes if no more LSAs advertise them.
+ */
bool
removeNameLsa(const ndn::Name& key);
+ /*! Returns whether a seq. no. from a certain router signals a new LSA.
+ \param key The name of the originating router.
+ \param seqNo The sequence number to check.
+ */
bool
isNameLsaNew(const ndn::Name& key, uint64_t seqNo);
@@ -69,19 +89,36 @@
const std::list<NameLsa>&
getNameLsdb();
- // functions related to Cor LSDB
+ /*! \brief Builds a cor. LSA for this router and installs it into the LSDB. */
bool
buildAndInstallOwnCoordinateLsa();
+ /*! \brief Finds a cor. LSA in the LSDB.
+ \param key The name of the originating router that published the LSA.
+ */
CoordinateLsa*
findCoordinateLsa(const ndn::Name& key);
+ /*! \brief Installs a cor. LSA into the LSDB.
+ \param clsa The cor. LSA to install.
+ */
bool
installCoordinateLsa(CoordinateLsa& clsa);
+ /*! \brief Removes a cor. LSA from the LSDB.
+ \param key The name of the router that published the LSA to remove.
+
+ Removes the coordinate LSA whose origin router name matches that
+ given by key. Additionally, ask the NPT to remove the prefix,
+ which will occur if no other LSAs point there.
+ */
bool
removeCoordinateLsa(const ndn::Name& key);
+ /*! \brief Returns whether a cor. LSA from a router is new or not.
+ \param key The name prefix of the originating router.
+ \param seqNo The sequence number of the candidate LSA.
+ */
bool
isCoordinateLsaNew(const ndn::Name& key, uint64_t seqNo);
@@ -91,22 +128,41 @@
const std::list<CoordinateLsa>&
getCoordinateLsdb();
- // functions related to Adj LSDB
+ //function related to Adj LSDB
+
+ /*! \brief Schedules a build of this router's LSA. */
void
scheduleAdjLsaBuild();
+ /*! \brief Wrapper event to build and install an adj. LSA for this router. */
bool
buildAndInstallOwnAdjLsa();
+ /*! \brief Removes an adj. LSA from the LSDB.
+ \param key The name of the publishing router whose LSA to remove.
+ */
bool
removeAdjLsa(const ndn::Name& key);
+ /*! \brief Returns whether an LSA is new.
+ \param key The name of the publishing router.
+ \param seqNo The seq. no. of the candidate LSA.
+
+ This function determines whether the LSA with the name key and
+ seq. no. seqNo would be new to this LSDB.
+ */
bool
isAdjLsaNew(const ndn::Name& key, uint64_t seqNo);
+ /*! \brief Installs an adj. LSA into the LSDB.
+ \param alsa The adj. LSA to add to the LSDB.
+ */
bool
installAdjLsa(AdjLsa& alsa);
+ /*! \brief Finds an adj. LSA in the LSDB.
+ \param key The name of the publishing router whose LSA to find.
+ */
AdjLsa*
findAdjLsa(const ndn::Name& key);
@@ -142,41 +198,80 @@
processInterest(const ndn::Name& name, const ndn::Interest& interest);
private:
+ /* \brief Add a name LSA to the LSDB if it isn't already there.
+ \param nlsa The candidade name LSA.
+ */
bool
addNameLsa(NameLsa& nlsa);
+ /*! \brief Returns whether the LSDB contains some LSA.
+ \param key The name of the publishing router whose LSA to check for.
+ */
bool
doesNameLsaExist(const ndn::Name& key);
-
+ /*! \brief Adds a cor. LSA to the LSDB if it isn't already there.
+ \param clsa The candidate cor. LSA.
+ */
bool
addCoordinateLsa(CoordinateLsa& clsa);
+ /*! \brief Returns whether a cor. LSA is in the LSDB.
+ \param key The name of the router that published the queried LSA.
+ */
bool
doesCoordinateLsaExist(const ndn::Name& key);
+ /*! \brief Attempts to construct an adj. LSA.
+
+ This function will attempt to construct an adjacency LSA. An LSA
+ can only be built when the status of all of the router's neighbors
+ is known. That is, when we are not currently trying to contact any
+ neighbor.
+ */
void
buildAdjLsa();
+ /*! \brief Adds an adj. LSA to the LSDB if it isn't already there.
+ \param alsa The candidate adj. LSA to add to the LSDB.
+ */
bool
addAdjLsa(AdjLsa& alsa);
+ /*! \brief Returns whether the LSDB contains an LSA.
+ \param key The name of a router whose LSA to check for in the LSDB.
+ */
bool
doesAdjLsaExist(const ndn::Name& key);
+ /*! \brief Schedules a refresh/expire event in the scheduler.
+ \param key The name of the router that published the LSA.
+ \param seqNo The seq. no. associated with the LSA.
+ \param expTime How many seconds to wait before triggering the event.
+ */
ndn::EventId
scheduleNameLsaExpiration(const ndn::Name& key, int seqNo,
const seconds& expTime);
+ /*! \brief Either allow to expire, or refresh a name LSA.
+ \param lsaKey The name of the router that published the LSA.
+ \param seqNo The seq. no. of the LSA to check.
+ */
void
exprireOrRefreshNameLsa(const ndn::Name& lsaKey, uint64_t seqNo);
PUBLIC_WITH_TESTS_ELSE_PRIVATE:
+ /*! \brief Schedules an expire/refresh event in the LSA.
+ \param key The name of the router whose LSA is in question.
+ \param seqNo The sequence number of the LSA to check.
+ \param expTime The number of seconds to wait before triggering the event.
+ */
ndn::EventId
scheduleAdjLsaExpiration(const ndn::Name& key, int seqNo,
const seconds& expTime);
private:
+
void
exprireOrRefreshAdjLsa(const ndn::Name& lsaKey, uint64_t seqNo);
@@ -188,6 +283,8 @@
exprireOrRefreshCoordinateLsa(const ndn::Name& lsaKey,
uint64_t seqNo);
+private:
+
void
putLsaData(const ndn::Interest& interest, const std::string& content);
@@ -205,7 +302,6 @@
processInterestForCoordinateLsa(const ndn::Interest& interest,
const ndn::Name& lsaKey,
uint64_t seqNo);
-
void
onContentValidated(const ndn::shared_ptr<const ndn::Data>& data);
@@ -222,19 +318,19 @@
uint64_t lsSeqNo, std::string& dataContent);
PUBLIC_WITH_TESTS_ELSE_PRIVATE:
- /**
- * @brief Error callback when SegmentFetcher fails to return an LSA
- *
- * In all error cases, a reattempt to fetch the LSA will be made.
- *
- * Segment validation can fail either because the packet does not have a
- * valid signature (fatal) or because some of the certificates in the trust chain
- * could not be fetched (non-fatal).
- *
- * Currently, the library does not provide clear indication (besides a plain-text message
- * in the error callback) of the reason for the failure nor the segment that failed
- * to be validated, thus we will continue to try to fetch the LSA until the deadline
- * is reached.
+ /*!
+ \brief Error callback when SegmentFetcher fails to return an LSA
+
+ In all error cases, a reattempt to fetch the LSA will be made.
+
+ Segment validation can fail either because the packet does not have a
+ valid signature (fatal) or because some of the certificates in the trust chain
+ could not be fetched (non-fatal).
+
+ Currently, the library does not provide clear indication (besides a plain-text message
+ in the error callback) of the reason for the failure nor the segment that failed
+ to be validated, thus we will continue to try to fetch the LSA until the deadline
+ is reached.
*/
void
onFetchLsaError(uint32_t errorCode,
@@ -245,11 +341,11 @@
ndn::Name lsaName,
uint64_t seqNo);
- /**
- * @brief Success callback when SegmentFetcher returns a valid LSA
- *
- * \param The base Interest used to fetch the LSA in the format:
- * /<network>/NLSR/LSA/<site>/%C1.Router/<router>/<lsa-type>/<seqNo>
+ /*!
+ \brief Success callback when SegmentFetcher returns a valid LSA
+
+ \param The base Interest used to fetch the LSA in the format:
+ /<network>/NLSR/LSA/<site>/%C1.Router/<router>/<lsa-type>/<seqNo>
*/
void
afterFetchLsa(const ndn::ConstBufferPtr& data, ndn::Name& interestName);
@@ -258,6 +354,7 @@
system_clock::TimePoint
getLsaExpirationTimePoint();
+ /*! \brief Cancels an event in the event scheduler. */
void
cancelScheduleLsaExpiringEvent(ndn::EventId eid);