fw: add HopLimit to strategy documentation
refs #4806
Change-Id: I4299c17cb3974efccdd908bcd2aea58ab75c12b4
diff --git a/daemon/fw/strategy.hpp b/daemon/fw/strategy.hpp
index 37d98bb..190f1f2 100644
--- a/daemon/fw/strategy.hpp
+++ b/daemon/fw/strategy.hpp
@@ -1,6 +1,6 @@
/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
/*
- * Copyright (c) 2014-2019, Regents of the University of California,
+ * Copyright (c) 2014-2020, Regents of the University of California,
* Arizona Board of Regents,
* Colorado State University,
* University Pierre & Marie Curie, Sorbonne University,
@@ -32,12 +32,12 @@
namespace nfd {
namespace fw {
-/** \brief represents a forwarding strategy
+/** \brief Represents a forwarding strategy
*/
class Strategy : noncopyable
{
public: // registry
- /** \brief register a strategy type
+ /** \brief Register a strategy type
* \tparam S subclass of Strategy
* \param strategyName strategy program name, must contain version
* \note It is permitted to register the same strategy type under multiple names,
@@ -56,7 +56,7 @@
};
}
- /** \return whether a strategy instance can be created from \p instanceName
+ /** \return Whether a strategy instance can be created from \p instanceName
* \param instanceName strategy instance name, may contain version and parameters
* \note This function finds a strategy type using same rules as \p create ,
* but does not attempt to construct an instance.
@@ -64,7 +64,7 @@
static bool
canCreate(const Name& instanceName);
- /** \return a strategy instance created from \p instanceName
+ /** \return A strategy instance created from \p instanceName
* \retval nullptr if !canCreate(instanceName)
* \throw std::invalid_argument strategy type constructor does not accept
* specified version or parameters
@@ -72,12 +72,12 @@
static unique_ptr<Strategy>
create(const Name& instanceName, Forwarder& forwarder);
- /** \return whether \p instanceNameA and \p instanceNameA will initiate same strategy type
+ /** \return Whether \p instanceNameA and \p instanceNameA will initiate same strategy type
*/
static bool
areSameType(const Name& instanceNameA, const Name& instanceNameB);
- /** \return registered versioned strategy names
+ /** \return Registered versioned strategy names
*/
static std::set<Name>
listRegistered();
@@ -94,7 +94,7 @@
~Strategy();
#ifdef DOXYGEN
- /** \return strategy program name
+ /** \return Strategy program name
*
* The strategy name is defined by the strategy program.
* It must end with a version component.
@@ -103,7 +103,7 @@
getStrategyName();
#endif
- /** \return strategy instance name
+ /** \return Strategy instance name
*
* The instance name is assigned during instantiation.
* It contains a version component, and may have extra parameter components.
@@ -114,7 +114,7 @@
return m_name;
}
- /** \return whether the afterNewNextHop trigger should be invoked for this strategy.
+ /** \return Whether the afterNewNextHop trigger should be invoked for this strategy.
*/
bool
wantNewNextHopTrigger() const
@@ -123,9 +123,10 @@
}
public: // triggers
- /** \brief trigger after Interest is received
+ /** \brief Trigger after Interest is received
*
* The Interest:
+ * - has not exceeded HopLimit
* - does not violate Scope
* - is not looped
* - cannot be satisfied by ContentStore
@@ -151,7 +152,7 @@
afterReceiveInterest(const FaceEndpoint& ingress, const Interest& interest,
const shared_ptr<pit::Entry>& pitEntry) = 0;
- /** \brief trigger before PIT entry is satisfied
+ /** \brief Trigger before PIT entry is satisfied
*
* This trigger is invoked when an incoming Data satisfies more than one PIT entry.
* The strategy can collect measurements information, but cannot manipulate Data forwarding.
@@ -174,7 +175,7 @@
beforeSatisfyInterest(const shared_ptr<pit::Entry>& pitEntry,
const FaceEndpoint& ingress, const Data& data);
- /** \brief trigger after a Data is matched in CS
+ /** \brief Trigger after a Data is matched in CS
*
* In the base class this method sends \p data to \p ingress
*/
@@ -182,7 +183,7 @@
afterContentStoreHit(const shared_ptr<pit::Entry>& pitEntry,
const FaceEndpoint& ingress, const Data& data);
- /** \brief trigger after Data is received
+ /** \brief Trigger after Data is received
*
* This trigger is invoked when an incoming Data satisfies exactly one PIT entry,
* and gives the strategy full control over Data forwarding.
@@ -209,7 +210,7 @@
afterReceiveData(const shared_ptr<pit::Entry>& pitEntry,
const FaceEndpoint& ingress, const Data& data);
- /** \brief trigger after Nack is received
+ /** \brief Trigger after Nack is received
*
* This trigger is invoked when an incoming Nack is received in response to
* an forwarded Interest.
@@ -234,14 +235,14 @@
afterReceiveNack(const FaceEndpoint& ingress, const lp::Nack& nack,
const shared_ptr<pit::Entry>& pitEntry);
- /** \brief trigger after Interest dropped for exceeding allowed retransmissions
+ /** \brief Trigger after Interest dropped (e.g., for exceeding allowed retransmissions)
*
* In the base class this method does nothing.
*/
virtual void
onDroppedInterest(const FaceEndpoint& egress, const Interest& interest);
- /** \brief trigger after new nexthop is added
+ /** \brief Trigger after new nexthop is added
*
* The strategy should decide whether to send the buffered Interests to the new nexthop.
* In the base class, this method does nothing.
@@ -250,7 +251,7 @@
afterNewNextHop(const fib::NextHop& nextHop, const shared_ptr<pit::Entry>& pitEntry);
protected: // actions
- /** \brief send Interest to egress
+ /** \brief Send Interest to egress
* \param pitEntry PIT entry
* \param egress face through which to send out the Interest and destination endpoint
* \param interest the Interest packet
@@ -259,7 +260,7 @@
sendInterest(const shared_ptr<pit::Entry>& pitEntry,
const FaceEndpoint& egress, const Interest& interest);
- /** \brief send \p data to \p egress
+ /** \brief Send \p data to \p egress
* \param pitEntry PIT entry
* \param data the Data packet
* \param egress face through which to send out the Data and destination endpoint
@@ -267,7 +268,7 @@
VIRTUAL_WITH_TESTS void
sendData(const shared_ptr<pit::Entry>& pitEntry, const Data& data, const FaceEndpoint& egress);
- /** \brief send \p data to all matched and qualified face-endpoint pairs
+ /** \brief Send \p data to all matched and qualified face-endpoint pairs
*
* A matched face is qualified if it is ad-hoc or it is NOT \p ingress
*
@@ -279,7 +280,7 @@
sendDataToAll(const shared_ptr<pit::Entry>& pitEntry,
const FaceEndpoint& ingress, const Data& data);
- /** \brief schedule the PIT entry for immediate deletion
+ /** \brief Schedule the PIT entry for immediate deletion
*
* This helper function sets the PIT entry expiry time to zero.
* The strategy should invoke this function when it concludes that the Interest cannot
@@ -291,7 +292,7 @@
this->setExpiryTimer(pitEntry, 0_ms);
}
- /** \brief send Nack to egress
+ /** \brief Send Nack to egress
* \param pitEntry PIT entry
* \param egress face through which to send out the Nack and destination endpoint
* \param header Nack header
@@ -305,7 +306,7 @@
m_forwarder.onOutgoingNack(pitEntry, egress, header);
}
- /** \brief send Nack to every face-endpoint pair that has an in-record, except those in \p exceptFaceEndpoints
+ /** \brief Send Nack to every face-endpoint pair that has an in-record, except those in \p exceptFaceEndpoints
* \param pitEntry PIT entry
* \param header NACK header
* \param exceptFaceEndpoints list of face-endpoint pairs that should be excluded from sending Nacks
@@ -324,7 +325,7 @@
}
protected: // accessors
- /** \brief performs a FIB lookup, considering Link object if present
+ /** \brief Performs a FIB lookup, considering Link object if present
*/
const fib::Entry&
lookupFib(const pit::Entry& pitEntry) const;
@@ -355,14 +356,14 @@
PartialName parameters; ///< parameter components
};
- /** \brief parse a strategy instance name
+ /** \brief Parse a strategy instance name
* \param input strategy instance name, may contain version and parameters
* \throw std::invalid_argument input format is unacceptable
*/
static ParsedInstanceName
parseInstanceName(const Name& input);
- /** \brief construct a strategy instance name
+ /** \brief Construct a strategy instance name
* \param input strategy instance name, may contain version and parameters
* \param strategyName strategy name with version but without parameters;
* typically this should be \p getStrategyName()
@@ -375,7 +376,7 @@
static Name
makeInstanceName(const Name& input, const Name& strategyName);
- /** \brief set strategy instance name
+ /** \brief Set strategy instance name
* \note This must be called by strategy subclass constructor.
*/
void
@@ -385,7 +386,7 @@
}
PUBLIC_WITH_TESTS_ELSE_PROTECTED: // setter
- /** \brief set whether the afterNewNextHop trigger should be invoked for this strategy
+ /** \brief Set whether the afterNewNextHop trigger should be invoked for this strategy
*/
void
enableNewNextHopTrigger(bool enabled)
@@ -410,7 +411,7 @@
private: // instance fields
Name m_name;
- /** \brief reference to the forwarder
+ /** \brief Reference to the forwarder
*
* Triggers can access forwarder indirectly via actions.
*/
@@ -424,7 +425,7 @@
} // namespace fw
} // namespace nfd
-/** \brief registers a strategy
+/** \brief Registers a strategy
*
* This macro should appear once in .cpp of each strategy.
*/