face: minor refactoring and Doxygen improvements
refs #3248
Change-Id: I8c44b4342b9d7b9e896dbc96fbf671d3e29bcb3c
diff --git a/src/face.hpp b/src/face.hpp
index fe6af03..c83a9ae 100644
--- a/src/face.hpp
+++ b/src/face.hpp
@@ -62,59 +62,65 @@
} // namespace nfd
/**
- * @brief Callback called when expressed Interest gets satisfied with a Data packet
+ * @brief Callback invoked when expressed Interest gets satisfied with a Data packet
*/
typedef function<void(const Interest&, const Data&)> DataCallback;
/**
- * @brief Callback called when Nack is sent in response to expressed Interest
+ * @brief Callback invoked when Nack is sent in response to expressed Interest
*/
typedef function<void(const Interest&, const lp::Nack&)> NackCallback;
/**
- * @brief Callback called when expressed Interest times out
+ * @brief Callback invoked when expressed Interest times out
*/
typedef function<void(const Interest&)> TimeoutCallback;
/**
- * @brief Callback called when expressed Interest gets satisfied with Data packet
+ * @brief Callback invoked when expressed Interest gets satisfied with Data packet
* @deprecated use DataCallback
*/
typedef function<void(const Interest&, Data&)> OnData;
/**
- * @brief Callback called when expressed Interest times out
+ * @brief Callback invoked when expressed Interest times out
* @deprecated use TimeoutCallback
*/
typedef function<void(const Interest&)> OnTimeout;
/**
- * @brief Callback called when incoming Interest matches the specified InterestFilter
+ * @brief Callback invoked when incoming Interest matches the specified InterestFilter
+ */
+typedef function<void(const InterestFilter&, const Interest&)> InterestCallback;
+
+/**
+ * @brief Callback invoked when incoming Interest matches the specified InterestFilter
+ * @deprecated use InterestCallback
*/
typedef function<void (const InterestFilter&, const Interest&)> OnInterest;
/**
- * @brief Callback called when registerPrefix or setInterestFilter command succeeds
+ * @brief Callback invoked when registerPrefix or setInterestFilter command succeeds
*/
typedef function<void(const Name&)> RegisterPrefixSuccessCallback;
/**
- * @brief Callback called when registerPrefix or setInterestFilter command fails
+ * @brief Callback invoked when registerPrefix or setInterestFilter command fails
*/
typedef function<void(const Name&, const std::string&)> RegisterPrefixFailureCallback;
/**
- * @brief Callback called when unregisterPrefix or unsetInterestFilter command succeeds
+ * @brief Callback invoked when unregisterPrefix or unsetInterestFilter command succeeds
*/
typedef function<void()> UnregisterPrefixSuccessCallback;
/**
- * @brief Callback called when unregisterPrefix or unsetInterestFilter command fails
+ * @brief Callback invoked when unregisterPrefix or unsetInterestFilter command fails
*/
typedef function<void(const std::string&)> UnregisterPrefixFailureCallback;
/**
- * @brief Abstraction to communicate with local or remote NDN forwarder
+ * @brief Provide a communication channel with local or remote NDN forwarder
*/
class Face : noncopyable
{
@@ -131,101 +137,99 @@
public: // constructors
/**
- * @brief Create a new Face using the default transport (UnixTransport)
+ * @brief Create Face using given transport (or default transport if omitted)
+ * @param transport the transport for lower layer communication. If nullptr,
+ * a default transport will be used. The default transport is
+ * determined from a FaceUri in NDN_CLIENT_TRANSPORT environ,
+ * a FaceUri in configuration file 'transport' key, or UnixTransport.
*
- * @throws ConfigFile::Error on configuration file parse failure
- * @throws ConfigFile::Error if configuration file specifies an unsupported protocol
+ * @throw ConfigFile::Error if @p transport is nullptr, and the configuration file cannot be
+ * parsed or specifies an unsupported protocol
+ * @note shared_ptr is passed by value because ownership is shared with this class
*/
- Face();
+ explicit
+ Face(shared_ptr<Transport> transport = nullptr);
/**
- * @brief Create a new Face using the default transport (UnixTransport)
+ * @brief Create Face using default transport and given io_service
*
- * @par Usage examples:
+ * Usage examples:
*
- * Face face1;
- * Face face2(face1.getIoService());
+ * @code
+ * Face face1;
+ * Face face2(face1.getIoService());
*
- * // Now the following ensures that events on both faces are processed
- * face1.processEvents();
- * // or face1.getIoService().run();
+ * // Now the following ensures that events on both faces are processed
+ * face1.processEvents();
+ * // or face1.getIoService().run();
+ * @endcode
*
- * @par or
+ * or
*
- * boost::asio::io_service ioService;
- * Face face1(ioService);
- * Face face2(ioService);
- * ...
+ * @code
+ * boost::asio::io_service ioService;
+ * Face face1(ioService);
+ * Face face2(ioService);
*
- * ioService.run();
+ * ioService.run();
+ * @endcode
*
* @param ioService A reference to boost::io_service object that should control all
* IO operations.
- * @throws ConfigFile::Error on configuration file parse failure
- * @throws ConfigFile::Error if configuration file specifies an unsupported protocol
+ * @throw ConfigFile::Error the configuration file cannot be parsed or specifies an unsupported protocol
*/
explicit
Face(boost::asio::io_service& ioService);
/**
- * @brief Create a new Face using TcpTransport
+ * @brief Create Face using TcpTransport
*
- * @param host The host of the NDN forwarder
- * @param port (optional) The port or service name of the NDN forwarder (**default**: "6363")
+ * @param host IP address or hostname of the NDN forwarder
+ * @param port port number or service name of the NDN forwarder (**default**: "6363")
*/
Face(const std::string& host, const std::string& port = "6363");
/**
- * @brief Create a new Face using the given Transport
- * @param transport the Transport used for communication. If nullptr, then the default
- * transport will be used.
- *
- * @throws ConfigFile::Error if @p transport is nullptr on configuration file parse failure
- * @throws ConfigFile::Error if @p transport is nullptr and the configuration file
- * specifies an unsupported protocol
- * @note shared_ptr is passed by value because ownership is shared with this class
- */
- explicit
- Face(shared_ptr<Transport> transport);
-
- /**
- * @brief Create a new Face using the given Transport and KeyChain instance
- * @param transport the Transport used for communication. If nullptr, then the default
- * transport will be used.
+ * @brief Create Face using given transport and KeyChain
+ * @param transport the transport for lower layer communication. If nullptr,
+ * a default transport will be used.
* @param keyChain the KeyChain to sign commands
*
- * @throws ConfigFile::Error if @p transport is nullptr on configuration file parse failure
- * @throws ConfigFile::Error if @p transport is nullptr and the configuration file
- * specifies an unsupported protocol
+ * @sa Face(shared_ptr<Transport>)
+ *
+ * @throw ConfigFile::Error if @p transport is nullptr, and the configuration file cannot be
+ * parsed or specifies an unsupported protocol
* @note shared_ptr is passed by value because ownership is shared with this class
*/
Face(shared_ptr<Transport> transport, KeyChain& keyChain);
/**
- * @brief Create a new Face using the given Transport and IO service object
- * @param transport the Transport used for communication. If nullptr, then the default
- * transport will be used.
+ * @brief Create Face using given transport and IO service
+ * @param transport the transport for lower layer communication. If nullptr,
+ * a default transport will be used.
* @param ioService the io_service that controls all IO operations
*
* @sa Face(boost::asio::io_service&)
+ * @sa Face(shared_ptr<Transport>)
*
- * @throws ConfigFile::Error if @p transport is nullptr on configuration file parse failure
- * @throws ConfigFile::Error if @p transport is nullptr and the configuration file
- * specifies an unsupported protocol
+ * @throw ConfigFile::Error if @p transport is nullptr, and the configuration file cannot be
+ * parsed or specifies an unsupported protocol
* @note shared_ptr is passed by value because ownership is shared with this class
*/
Face(shared_ptr<Transport> transport, boost::asio::io_service& ioService);
/**
- * @brief Create a new Face using the given Transport and IO service object
- * @param transport the Transport used for communication. If nullptr, then the default
- * transport will be used.
+ * @brief Create a new Face using given Transport and IO service
+ * @param transport the transport for lower layer communication. If nullptr,
+ * a default transport will be used.
* @param ioService the io_service that controls all IO operations
* @param keyChain the KeyChain to sign commands
*
- * @throws ConfigFile::Error if @p transport is nullptr on configuration file parse failure
- * @throws ConfigFile::Error if @p transport is nullptr and the configuration file
- * specifies an unsupported protocol
+ * @sa Face(boost::asio::io_service&)
+ * @sa Face(shared_ptr<Transport>, KeyChain&)
+ *
+ * @throw ConfigFile::Error if @p transport is nullptr, and the configuration file cannot be
+ * parsed or specifies an unsupported protocol
* @note shared_ptr is passed by value because ownership is shared with this class
*/
Face(shared_ptr<Transport> transport, boost::asio::io_service& ioService, KeyChain& keyChain);
@@ -257,7 +261,7 @@
*
* @return The pending interest ID which can be used with removePendingInterest
*
- * @throws Error when Interest size exceeds maximum limit (MAX_NDN_PACKET_SIZE)
+ * @throw Error when Interest size exceeds maximum limit (MAX_NDN_PACKET_SIZE)
*
* @deprecated use expressInterest(Interest, DataCallback, NackCallback, TimeoutCallback)
*/
@@ -276,7 +280,7 @@
*
* @return Opaque pending interest ID which can be used with removePendingInterest
*
- * @throws Error when Interest size exceeds maximum limit (MAX_NDN_PACKET_SIZE)
+ * @throw Error when Interest size exceeds maximum limit (MAX_NDN_PACKET_SIZE)
*
* @deprecated use expressInterest(Interest, DataCallback, NackCallback, TimeoutCallback)
*/
@@ -329,7 +333,7 @@
*/
const RegisteredPrefixId*
setInterestFilter(const InterestFilter& interestFilter,
- const OnInterest& onInterest,
+ const InterestCallback& onInterest,
const RegisterPrefixFailureCallback& onFailure,
const security::SigningInfo& signingInfo = security::SigningInfo(),
uint64_t flags = nfd::ROUTE_FLAG_CHILD_INHERIT);
@@ -357,7 +361,7 @@
*/
const RegisteredPrefixId*
setInterestFilter(const InterestFilter& interestFilter,
- const OnInterest& onInterest,
+ const InterestCallback& onInterest,
const RegisterPrefixSuccessCallback& onSuccess,
const RegisterPrefixFailureCallback& onFailure,
const security::SigningInfo& signingInfo = security::SigningInfo(),
@@ -377,7 +381,7 @@
*/
const InterestFilterId*
setInterestFilter(const InterestFilter& interestFilter,
- const OnInterest& onInterest);
+ const InterestCallback& onInterest);
#ifdef NDN_FACE_KEEP_DEPRECATED_REGISTRATION_SIGNING
/**
@@ -634,7 +638,7 @@
* extra copy of the Data packet to ensure validity of published Data until
* asynchronous put() operation finishes.
*
- * @throws Error when Data size exceeds maximum limit (MAX_NDN_PACKET_SIZE)
+ * @throw Error when Data size exceeds maximum limit (MAX_NDN_PACKET_SIZE)
*/
void
put(const Data& data);
@@ -685,7 +689,7 @@
shutdown();
/**
- * @brief Get reference to IO service object
+ * @return reference to IO service object
*/
boost::asio::io_service&
getIoService()
@@ -695,21 +699,20 @@
NDN_CXX_PUBLIC_WITH_TESTS_ELSE_PROTECTED:
/**
- * @brief Get the underlying transport of the face
+ * @return underlying transport
*/
shared_ptr<Transport>
getTransport();
private:
-
/**
- * @throws ConfigFile::Error on parse error and unsupported protocols
+ * @throw ConfigFile::Error on parse error and unsupported protocols
*/
shared_ptr<Transport>
makeDefaultTransport();
/**
- * @throws Face::Error on unsupported protocol
+ * @throw Face::Error on unsupported protocol
* @note shared_ptr is passed by value because ownership is transferred to this function
*/
void
@@ -729,11 +732,12 @@
shared_ptr<Transport> m_transport;
- /** @brief if not null, a pointer to an internal KeyChain owned by Face
- * @note if a KeyChain is supplied to constructor, this pointer will be null,
- * and the passed KeyChain is given to nfdController;
- * currently Face does not keep the KeyChain passed in constructor
- * because it's not needed, but this may change in the future
+ /**
+ * @brief if not null, a pointer to an internal KeyChain owned by Face
+ * @note if a KeyChain is supplied to constructor, this pointer will be null,
+ * and the passed KeyChain is given to nfdController;
+ * currently Face does not keep the KeyChain passed in constructor
+ * because it's not needed, but this may change in the future
*/
unique_ptr<KeyChain> m_internalKeyChain;