docs: API documentation fixes
Change-Id: I1088a156c9ac055f974900454647dcb9a7b7ec54
Refs: #3210
diff --git a/docs/doxygen.conf.in b/docs/doxygen.conf.in
index 82e9e3e..d3d5b2a 100644
--- a/docs/doxygen.conf.in
+++ b/docs/doxygen.conf.in
@@ -801,7 +801,7 @@
# that contain example code fragments that are included (see the \include
# command).
-EXAMPLE_PATH = examples/
+EXAMPLE_PATH =
# If the value of the EXAMPLE_PATH tag contains directories, you can use the
# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and
@@ -1782,18 +1782,6 @@
XML_OUTPUT = xml
-# The XML_SCHEMA tag can be used to specify a XML schema, which can be used by a
-# validating XML parser to check the syntax of the XML files.
-# This tag requires that the tag GENERATE_XML is set to YES.
-
-XML_SCHEMA =
-
-# The XML_DTD tag can be used to specify a XML DTD, which can be used by a
-# validating XML parser to check the syntax of the XML files.
-# This tag requires that the tag GENERATE_XML is set to YES.
-
-XML_DTD =
-
# If the XML_PROGRAMLISTING tag is set to YES doxygen will dump the program
# listings (including syntax highlighting and cross-referencing information) to
# the XML output. Note that enabling this will significantly increase the size
@@ -2241,7 +2229,7 @@
# Minimum value: 0, maximum value: 10000, default value: 50.
# This tag requires that the tag HAVE_DOT is set to YES.
-DOT_GRAPH_MAX_NODES = 50
+DOT_GRAPH_MAX_NODES = 10000
# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the graphs
# generated by dot. A depth value of 3 means that only nodes reachable from the
diff --git a/src/encoding/block-helpers.hpp b/src/encoding/block-helpers.hpp
index 5f26b17..fcc8458 100644
--- a/src/encoding/block-helpers.hpp
+++ b/src/encoding/block-helpers.hpp
@@ -82,7 +82,7 @@
prependStringBlock(EncodingImpl<TAG>& encoder, uint32_t type, const std::string& value);
/**
- * @brief Create a TLV block type @p type with value from a string @p
+ * @brief Create a TLV block type @p type with value from a string @p value
* @see prependStringBlock, readString
*/
Block
diff --git a/src/encoding/encoder.hpp b/src/encoding/encoder.hpp
index f5f40ae..a8092d1 100644
--- a/src/encoding/encoder.hpp
+++ b/src/encoding/encoder.hpp
@@ -159,6 +159,7 @@
/**
* @brief Reserve @p size bytes for the underlying buffer
+ * @param size amount of bytes to reserve in the underlying buffer
* @param addInFront if true, then @p size bytes will be available in front (i.e., subsequent call
* to prepend* will not need to allocate memory). If false, then reservation will be done
* at the end of the buffer (i.d., for subsequent append* calls)
diff --git a/src/face.hpp b/src/face.hpp
index f002e04..80e7930 100644
--- a/src/face.hpp
+++ b/src/face.hpp
@@ -447,8 +447,10 @@
* @param onFailure A callback to be called when prefixRegister command fails
* @param signingInfo (optional) Signing parameters. When omitted, a default parameters
* used in the signature will be used.
+ * @param flags Prefix registration flags
*
* @return The registered prefix ID which can be used with unregisterPrefix
+ * @see nfd::RouteFlags
*/
const RegisteredPrefixId*
registerPrefix(const Name& prefix,
diff --git a/src/link.hpp b/src/link.hpp
index e4e9f38..03b83a6 100644
--- a/src/link.hpp
+++ b/src/link.hpp
@@ -130,12 +130,12 @@
/**
* @brief Decode from the wire format
* @warning This method does not preserve the relative order between delegations.
- * To get a delegation by index, use \p getDelegationFromWire method.
+ * To get a delegation by index, use @p getDelegationFromWire method.
*/
void
wireDecode(const Block& wire);
- /** @brief gets the delegation at \p index from \p block
+ /** @brief gets the delegation at @p index from @p block
* @param block wire format of a Link object
* @param index 0-based index of a delegation in the Link object
* @return delegation preference and name
@@ -144,9 +144,10 @@
static std::tuple<uint32_t, Name>
getDelegationFromWire(const Block& block, size_t index);
- /** @brief finds index of a delegation with \p delegationName from \p block
+ /** @brief finds index of a delegation with @p delegationName from @p block
* @param block wire format of a Link object
- * @return 0-based index of the first delegation with \p delegationName ,
+ * @param delegationName delegation name in the Link object
+ * @return 0-based index of the first delegation with @p delegationName ,
* or -1 if no such delegation exists
*/
static ssize_t
diff --git a/src/mgmt/dispatcher.hpp b/src/mgmt/dispatcher.hpp
index 7c6121d..1e1195e 100644
--- a/src/mgmt/dispatcher.hpp
+++ b/src/mgmt/dispatcher.hpp
@@ -193,6 +193,9 @@
* relPrefixes in ControlCommands, StatusDatasets, NotificationStreams must be
* non-overlapping
* (no relPrefix is a prefix of another relPrefix)
+ * \param authorization Callback to authorize the incoming commands
+ * \param validateParams Callback to validate parameters of the incoming commands
+ * \param handler Callback to handle the commands
* \pre no top-level prefix has been added
* \throw std::out_of_range \p relPrefix overlaps with an existing relPrefix
* \throw std::domain_error one or more top-level prefix has been added
@@ -224,6 +227,7 @@
* non-overlapping
* (no relPrefix is a prefix of another relPrefix)
* \param authorization should set identity to Name() if the dataset is public
+ * \param handler Callback to process the incoming dataset requests
* \pre no top-level prefix has been added
* \throw std::out_of_range \p relPrefix overlaps with an existing relPrefix
* \throw std::domain_error one or more top-level prefix has been added
diff --git a/src/security/identity.hpp b/src/security/identity.hpp
index d77428d..0ac8201 100644
--- a/src/security/identity.hpp
+++ b/src/security/identity.hpp
@@ -74,7 +74,7 @@
getName() const;
/**
- * @brief Get a key with id @keyId.
+ * @brief Get a key with id @p keyId.
*
* @param keyId The id of the key to get.
* @throw Pib::Error if the key does not exist.
diff --git a/src/security/pib-impl.hpp b/src/security/pib-impl.hpp
index 080dc48..90e7dfc 100644
--- a/src/security/pib-impl.hpp
+++ b/src/security/pib-impl.hpp
@@ -274,7 +274,7 @@
getCertificatesOfKey(const Name& identity, const name::Component& keyId) const = 0;
/**
- * @brief Set a cert with name @p certName as the default of a key with id @keyId of @identity.
+ * @brief Set a cert with name @p certName as the default of a key with id @p keyId of @p identity.
*
* @param identity The name of the belonging identity.
* @param keyId The key id.
@@ -286,7 +286,7 @@
const Name& certName) = 0;
/**
- * @brief Get the default certificate of a key with id @keyId of @identity.
+ * @brief Get the default certificate of a key with id @p keyId of @p identity.
*
* @param identity The name of the belonging identity.
* @param keyId The key id.
diff --git a/src/security/pib-sqlite3.hpp b/src/security/pib-sqlite3.hpp
index a9fabe9..c63fb37 100644
--- a/src/security/pib-sqlite3.hpp
+++ b/src/security/pib-sqlite3.hpp
@@ -60,239 +60,76 @@
public: // TpmLocator management
- /**
- * @brief Set the corresponding TPM information to @p tpmLocator.
- *
- * If the provided @p tpmLocator is different from the existing one, the
- * content in PIB will be cleaned up, otherwise nothing will be changed.
- *
- * @param tpmLocator The name for the new TPM locator
- */
virtual void
setTpmLocator(const std::string& tpmLocator) NDN_CXX_DECL_FINAL;
- /**
- * @brief Get TPM Locator
- */
virtual std::string
getTpmLocator() const NDN_CXX_DECL_FINAL;
public: // Identity management
- /**
- * @brief Check the existence of an identity.
- *
- * @param identity The name of the identity.
- * @return true if the identity exists, otherwise false.
- */
virtual bool
hasIdentity(const Name& identity) const NDN_CXX_DECL_FINAL;
- /**
- * @brief Add an identity.
- *
- * If the identity already exists, do nothing.
- * If no default identity has been set, set the added one as default identity.
- *
- * @param identity The name of the identity to add.
- */
virtual void
addIdentity(const Name& identity) NDN_CXX_DECL_FINAL;
- /**
- * @brief Remove an identity
- *
- * If the identity does not exist, do nothing.
- * Remove related keys and certificates as well.
- *
- * @param identity The name of the identity to remove.
- */
virtual void
removeIdentity(const Name& identity) NDN_CXX_DECL_FINAL;
- /**
- * @brief Get the name of all the identities
- */
virtual std::set<Name>
getIdentities() const NDN_CXX_DECL_FINAL;
- /**
- * @brief Set an identity with name @p identityName as the default identity.
- *
- * Since adding an identity only requires the identity name, create the
- * identity if it does not exist.
- *
- * @param identityName The name for the default identity.
- */
virtual void
setDefaultIdentity(const Name& identityName) NDN_CXX_DECL_FINAL;
- /**
- * @brief Get the default identity.
- *
- * @return The name for the default identity.
- * @throws Pib::Error if no default identity.
- */
virtual Name
getDefaultIdentity() const NDN_CXX_DECL_FINAL;
public: // Key management
- /**
- * @brief Check the existence of a key.
- *
- * @param identity The name of the belonged identity.
- * @param keyId The key id component.
- * @return true if the key exists, otherwise false. Return false if the identity does not exist
- */
virtual bool
hasKey(const Name& identity, const name::Component& keyId) const NDN_CXX_DECL_FINAL;
- /**
- * @brief Add a key.
- *
- * If the key already exists, do nothing.
- * If the identity does not exist, add the identity as well.
- * If no default key of the identity has been set, set the added one as default
- * key of the identity.
- *
- * @param identity The name of the belonged identity.
- * @param keyId The key id component.
- * @param publicKey The public key bits.
- */
virtual void
addKey(const Name& identity, const name::Component& keyId, const PublicKey& publicKey) NDN_CXX_DECL_FINAL;
- /**
- * @brief Remove a key.
- *
- * If the key does not exist, do nothing.
- * Remove related certificates as well.
- *
- * @param identity The name of the belonged identity.
- * @param keyId The key id component.
- */
virtual void
removeKey(const Name& identity, const name::Component& keyId) NDN_CXX_DECL_FINAL;
- /**
- * @brief Get the key bits of a key.
- *
- * @param identity The name of the belonged identity.
- * @param keyId The key id component.
- * @return key bits
- * @throws Pib::Error if the key does not exist.
- */
virtual PublicKey
getKeyBits(const Name& identity, const name::Component& keyId) const NDN_CXX_DECL_FINAL;
- /**
- * @brief Get all the key ids of an identity with name @p identity
- *
- * The returned key ids can be used to create a KeyContainer.
- * With key id, identity name, backend implementation, one can create a Key frontend instance.
- *
- * @return the key id name component set. If the identity does not exist, return an empty set.
- */
virtual std::set<name::Component>
getKeysOfIdentity(const Name& identity) const NDN_CXX_DECL_FINAL;
- /**
- * @brief Set an key with id @p keyId as the default key of an identity with name @p identity.
- *
- * @param identity The name of the belonged identity.
- * @param keyId The key id component.
- * @throws Pib::Error if the key does not exist.
- */
virtual void
setDefaultKeyOfIdentity(const Name& identity, const name::Component& keyId) NDN_CXX_DECL_FINAL;
- /**
- * @brief Get the id of the default key of an identity with name @p identity.
- *
- * @param identity The name of the belonged identity.
- * @throws Pib::Error if no default key or the identity does not exist.
- */
virtual name::Component
getDefaultKeyOfIdentity(const Name& identity) const NDN_CXX_DECL_FINAL;
public: // Certificate Management
- /**
- * @brief Check the existence of a certificate with name @p certName.
- *
- * @param certName The name of the certificate.
- * @return true if the certificate exists, otherwise false.
- */
virtual bool
hasCertificate(const Name& certName) const NDN_CXX_DECL_FINAL;
- /**
- * @brief Add a certificate.
- *
- * If the certificate already exists, do nothing.
- * If the key or identity do not exist, add them as well.
- * If no default certificate of the key has been set, set the added one as
- * default certificate of the key.
- *
- * @param certificate The certificate to add.
- */
virtual void
addCertificate(const IdentityCertificate& certificate) NDN_CXX_DECL_FINAL;
- /**
- * @brief Remove a certificate with name @p certName.
- *
- * If the certificate does not exist, do nothing.
- *
- * @param certName The name of the certificate.
- */
virtual void
removeCertificate(const Name& certName) NDN_CXX_DECL_FINAL;
- /**
- * @brief Get a certificate with name @p certName.
- *
- * @param certName The name of the certificate.
- * @return the certificate.
- * @throws Pib::Error if the certificate does not exist.
- */
virtual IdentityCertificate
getCertificate(const Name& certName) const NDN_CXX_DECL_FINAL;
- /**
- * @brief Get a list of certificate names of a key with id @p keyId of @p identity.
- *
- * The returned certificate names can be used to create a CertificateContainer.
- * With certificate name and backend implementation, one can obtain the certificate directly.
- *
- * @param identity The name of the belonging identity.
- * @param keyId The key id.
- * @return The certificate name set. If the key does not exist, return an empty set.
- */
virtual std::set<Name>
getCertificatesOfKey(const Name& identity, const name::Component& keyId) const NDN_CXX_DECL_FINAL;
- /**
- * @brief Set a cert with name @p certName as the default of a key with id @keyId of @identity.
- *
- * @param identity The name of the belonging identity.
- * @param keyId The key id.
- * @param certName The name of the certificate.
- * @throws Pib::Error if the certificate with name @p certName does not exist.
- */
virtual void
setDefaultCertificateOfKey(const Name& identity, const name::Component& keyId,
const Name& certName) NDN_CXX_DECL_FINAL;
- /**
- * @brief Get the default certificate of a key with id @keyId of @identity.
- *
- * @param identity The name of the belonging identity.
- * @param keyId The key id.
- * @return a pointer to the certificate, null if no default certificate for the key.
- * @throws Pib::Error if the default certificate does not exist.
- */
virtual IdentityCertificate
getDefaultCertificateOfKey(const Name& identity, const name::Component& keyId) const NDN_CXX_DECL_FINAL;
diff --git a/src/tag.hpp b/src/tag.hpp
index b1b995e..195d821 100644
--- a/src/tag.hpp
+++ b/src/tag.hpp
@@ -38,11 +38,13 @@
* @return an integer that uniquely identifies this Tag type
* @sa http://redmine.named-data.net/projects/ndn-cxx/wiki/PacketTagTypes
*/
- // static constexpr int
- // getTypeId()
- // {
- // return <type-identifier>;
- // }
+#ifdef DOXYGEN
+ static constexpr int
+ getTypeId()
+ {
+ return <type-identifier>;
+ }
+#endif // DOXYGEN
};
inline
diff --git a/src/util/digest.hpp b/src/util/digest.hpp
index 0fdb3a3..ea1538e 100644
--- a/src/util/digest.hpp
+++ b/src/util/digest.hpp
@@ -64,7 +64,7 @@
Digest();
/**
- * @brief Create digest of the input stream @p
+ * @brief Create digest of the input stream @p is
* @param is input stream
*/
explicit
diff --git a/src/util/ethernet.cpp b/src/util/ethernet.cpp
index c128d37..40d9391 100644
--- a/src/util/ethernet.cpp
+++ b/src/util/ethernet.cpp
@@ -45,7 +45,7 @@
data()[5] = a6;
}
-Address::Address(const uint8_t octets[])
+Address::Address(const uint8_t octets[ADDR_LEN])
{
std::copy(octets, octets + size(), begin());
}
@@ -137,10 +137,8 @@
} // namespace ndn
-using ndn::util::ethernet::Address;
-
std::size_t
-std::hash<Address>::operator()(const Address& a) const noexcept
+std::hash<ndn::util::ethernet::Address>::operator()(const ndn::util::ethernet::Address& a) const noexcept
{
return boost::hash_range(a.cbegin(), a.cend());
}
diff --git a/src/util/face-uri.hpp b/src/util/face-uri.hpp
index 0e51012..f7cbe41 100644
--- a/src/util/face-uri.hpp
+++ b/src/util/face-uri.hpp
@@ -164,9 +164,10 @@
* \param onSuccess function to call after this FaceUri is converted to canonical form
* \note A new FaceUri in canonical form will be created; this FaceUri is unchanged.
* \param onFailure function to call if this FaceUri cannot be converted to canonical form
- * \param timeout maximum allowable duration of the operations.
- * It's intentional not to provide a default value: the caller should set
- * a reasonable value in balance between network delay and user experience.
+ * \param io reference to `boost::asio::io_service` instance
+ * \param timeout maximum allowable duration of the operations.
+ * It's intentional not to provide a default value: the caller should set
+ * a reasonable value in balance between network delay and user experience.
*/
void
canonize(const CanonizeSuccessCallback& onSuccess,
diff --git a/src/util/in-memory-storage.hpp b/src/util/in-memory-storage.hpp
index 9bec775..5e800c2 100644
--- a/src/util/in-memory-storage.hpp
+++ b/src/util/in-memory-storage.hpp
@@ -157,7 +157,8 @@
find(const Name& name);
/** @brief Deletes in-memory storage entry by prefix by default.
- * @param[in] isPrefix If it is clear, the function will only delete the
+ * @param prefix Exact name of a prefix of the data to remove
+ * @param isPrefix If false, the function will only delete the
* entry completely matched with the prefix according to canonical ordering.
* For this case, user should substitute the prefix with full name.
*
diff --git a/src/util/segment-fetcher.hpp b/src/util/segment-fetcher.hpp
index f2fbe38..fb8f6d7 100644
--- a/src/util/segment-fetcher.hpp
+++ b/src/util/segment-fetcher.hpp
@@ -47,31 +47,31 @@
/**
* @brief Utility class to fetch latest version of the segmented data
*
- * SegmentFetcher assumes that the data is named /<prefix>/<version>/<segment>,
+ * SegmentFetcher assumes that the data is named `/<prefix>/<version>/<segment>`,
* where:
- * - <prefix> is the specified prefix,
- * - <version> is an unknown version that needs to be discovered, and
- * - <segment> is a segment number (number of segments is unknown and is controlled
+ * - `<prefix>` is the specified prefix,
+ * - `<version>` is an unknown version that needs to be discovered, and
+ * - `<segment>` is a segment number (number of segments is unknown and is controlled
* by `FinalBlockId` field in at least the last Data packet
*
* The following logic is implemented in SegmentFetcher:
*
* 1. Express first interest to discover version:
*
- * >> Interest: /<prefix>?ChildSelector=1&MustBeFresh=yes
+ * >> Interest: `/<prefix>?ChildSelector=1&MustBeFresh=yes`
*
- * 2. Infer the latest version of Data: <version> = Data.getName().get(-2)
+ * 2. Infer the latest version of Data: `<version> = Data.getName().get(-2)`
*
* 3. If segment number in the retrieved packet == 0, go to step 5.
*
* 4. Send Interest for segment 0:
*
- * >> Interest: /<prefix>/<version>/<segment=0>
+ * >> Interest: `/<prefix>/<version>/<segment=0>`
*
* 5. Keep sending Interests for the next segment while the retrieved Data does not have
* FinalBlockId or FinalBlockId != Data.getName().get(-1).
*
- * >> Interest: /<prefix>/<version>/<segment=(N+1))>
+ * >> Interest: `/<prefix>/<version>/<segment=(N+1))>`
*
* 6. Fire onCompletion callback with memory block that combines content part from all
* segmented objects.