Assorted API documentation improvements
Change-Id: Iee905b6d9b590d66129b8c7272138c9c39cca21f
diff --git a/.jenkins.d/40-headers-check.sh b/.jenkins.d/40-headers-check.sh
index 486bb4e..861d8c9 100755
--- a/.jenkins.d/40-headers-check.sh
+++ b/.jenkins.d/40-headers-check.sh
@@ -5,6 +5,9 @@
# It's intentional not to use `set -e`, because this script wants to check all headers
# (similar to running all test cases), instead of failing at the first error.
+PROJ=ndn-cxx
+PCFILE=libndn-cxx
+
if [[ -n $DISABLE_HEADERS_CHECK ]]; then
echo 'Skipping headers check.'
exit 0
@@ -16,8 +19,8 @@
CXX=${CXX:-g++}
STD=-std=c++14
-CXXFLAGS="-O2 -Wall -Wno-unneeded-internal-declaration -Wno-unused-const-variable $(pkg-config --cflags libndn-cxx)"
-INCLUDEDIR="$(pkg-config --variable=includedir libndn-cxx)"/ndn-cxx
+CXXFLAGS="-O2 -Wall -Wno-unneeded-internal-declaration -Wno-unused-const-variable $(pkg-config --cflags libndn-cxx $PCFILE)"
+INCLUDEDIR="$(pkg-config --variable=includedir $PCFILE)"/$PROJ
echo "Using: $CXX $STD $CXXFLAGS"
@@ -31,7 +34,7 @@
done < <(find "$INCLUDEDIR" -name '*.hpp' -type f -print0 2>/dev/null)
if [[ $NCHECKED -eq 0 ]]; then
- echo 'No headers found. Is ndn-cxx installed?'
+ echo "No headers found. Is $PROJ installed?"
exit 1
else
echo "$NCHECKED headers checked."
diff --git a/ndn-cxx/metadata-object.hpp b/ndn-cxx/metadata-object.hpp
index 3ee3fe8..2e23f80 100644
--- a/ndn-cxx/metadata-object.hpp
+++ b/ndn-cxx/metadata-object.hpp
@@ -33,16 +33,17 @@
/**
* @brief Class for RDR-style metadata encoding/decoding.
*
- * The interest and data packets dealing with metadata (called "discovery interest"
- * and "metadata", respectively) follow a specific format.
- * @see https://redmine.named-data.net/projects/ndn-tlv/wiki/RDR
+ * Realtime %Data Retrieval (RDR) is a protocol for discovering the latest version number
+ * of a given data collection. The Interest and Data packets dealing with metadata (called
+ * "discovery interest" and "metadata object", respectively) follow a specific format.
*
- * Realtime Data Retrieval (RDR) is a protocol for discovering the latest version number
- * of a given data collection. There are two names in an RDR metadata object:
+ * There are two names in an RDR metadata object:
* @li the **versioned name** is a prefix of the data collection, and generally
* contains a version component. It appears in the Content element of the metadata object.
* @li the **metadata name** is the name of the metadata object itself, and includes
* a keyword name component `32=metadata`, as well as version and segment components.
+ *
+ * @sa https://redmine.named-data.net/projects/ndn-tlv/wiki/RDR
*/
class MetadataObject
{
@@ -98,7 +99,7 @@
* @brief Set the versioned name
*
* Any metadata packet carries a versioned name in its payload where it shows the name
- * and the latest version of a data stream. For instance, `/ndn/test/%FD%97%47%1E%6C` is
+ * and the latest version of a data stream. For instance, `/ndn/test/v=2538020460` is
* a versioned name that shows the latest version of `/ndn/test`.
*/
MetadataObject&
diff --git a/ndn-cxx/name-component.hpp b/ndn-cxx/name-component.hpp
index 0f3aa31..eac758b 100644
--- a/ndn-cxx/name-component.hpp
+++ b/ndn-cxx/name-component.hpp
@@ -93,11 +93,16 @@
void
setConventionDecoding(Convention convention);
-/** @brief Represents a name component.
+/**
+ * @brief Represents a name component.
*
- * The @c Component class provides a read-only view of a @c Block interpreted as a name component.
- * Although it inherits mutation methods from @c Block base class, they must not be used, because
- * the enclosing @c Name would not be updated correctly.
+ * The Component class provides a read-only view of a Block interpreted as a name component.
+ * Although it inherits mutation methods from the Block base class, they must not be used,
+ * because the enclosing Name would not be updated correctly.
+ *
+ * A name component is considered *invalid* if its TLV-TYPE is outside the range `[1, 65535]`,
+ * or, if it is an `ImplicitSha256DigestComponent` or a `ParametersSha256DigestComponent`,
+ * its TLV-LENGTH is not 32.
*/
class Component : public Block
{
@@ -110,23 +115,23 @@
public: // constructors
/**
- * @brief Construct a NameComponent of TLV-TYPE @p type, using empty TLV-VALUE.
- * @throw Error the NameComponent is invalid (see @c ensureValid).
+ * @brief Construct a NameComponent of TLV-TYPE @p type and with empty TLV-VALUE.
+ * @throw Error the NameComponent is invalid.
*/
explicit
Component(uint32_t type = tlv::GenericNameComponent);
/**
* @brief Construct a NameComponent from @p block.
- * @throw Error the NameComponent is invalid (see @c ensureValid).
+ * @throw Error the NameComponent is invalid.
*
- * This contructor enables implicit conversion from @c Block.
+ * This contructor enables implicit conversion from a Block.
*/
Component(const Block& wire);
/**
* @brief Construct a NameComponent of TLV-TYPE @p type, using TLV-VALUE from @p buffer.
- * @throw Error the NameComponent is invalid (see @c ensureValid).
+ * @throw Error the NameComponent is invalid.
*
* This constructor does not copy the underlying buffer, but retains a pointer to it.
* Therefore, the caller must not change the underlying buffer.
@@ -135,7 +140,7 @@
/**
* @brief Construct a GenericNameComponent, using TLV-VALUE from @p buffer.
- * @throw Error the NameComponent is invalid (see @c ensureValid).
+ * @throw Error the NameComponent is invalid.
*
* This constructor does not copy the underlying buffer, but retains a pointer to it.
* Therefore, the caller must not change the underlying buffer.
@@ -478,7 +483,7 @@
public: // commonly used TLV-TYPEs
/**
- * @brief Check if the component is GenericComponent
+ * @brief Check if the component is GenericNameComponent
*/
bool
isGeneric() const;
@@ -579,10 +584,6 @@
private:
/**
* @brief Throw Error if this Component is invalid.
- *
- * A name component is invalid if its TLV-TYPE is outside the [1, 65535] range.
- * Additionally, if it is an ImplicitSha256DigestComponent or a ParametersSha256DigestComponent,
- * its TLV-LENGTH must be 32.
*/
void
ensureValid() const;
diff --git a/ndn-cxx/prefix-announcement.hpp b/ndn-cxx/prefix-announcement.hpp
index c446213..387174c 100644
--- a/ndn-cxx/prefix-announcement.hpp
+++ b/ndn-cxx/prefix-announcement.hpp
@@ -1,6 +1,6 @@
/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
/*
- * Copyright (c) 2013-2020 Regents of the University of California.
+ * Copyright (c) 2013-2021 Regents of the University of California.
*
* This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
*
@@ -22,13 +22,16 @@
#ifndef NDN_CXX_PREFIX_ANNOUNCEMENT_HPP
#define NDN_CXX_PREFIX_ANNOUNCEMENT_HPP
+#include "ndn-cxx/data.hpp"
#include "ndn-cxx/security/key-chain.hpp"
namespace ndn {
-/** \brief A prefix announcement object that represents an application's intent of registering a
- * prefix toward itself.
- * \sa https://redmine.named-data.net/projects/nfd/wiki/PrefixAnnouncement
+/**
+ * \brief A prefix announcement object that represents an application's intent
+ * of registering a prefix toward itself.
+ *
+ * \sa https://redmine.named-data.net/projects/nfd/wiki/PrefixAnnouncement
*/
class PrefixAnnouncement
{
@@ -123,8 +126,9 @@
optional<security::ValidityPeriod> m_validity;
};
-/** \brief Test whether two prefix announcements has the same name, expiration period,
- * and validity period.
+/**
+ * \brief Test whether two prefix announcements have the same name, expiration period,
+ * and validity period.
*/
bool
operator==(const PrefixAnnouncement& lhs, const PrefixAnnouncement& rhs);
@@ -135,9 +139,10 @@
return !(lhs == rhs);
}
-/** \brief Print prefix announcement to a stream.
+/**
+ * \brief Print prefix announcement to a stream.
*
- * This string is for debugging purpose. Its syntax is not public API.
+ * The output is for debugging purposes only. The format may change at any time without notice.
*/
std::ostream&
operator<<(std::ostream& os, const PrefixAnnouncement& pa);
diff --git a/ndn-cxx/security/key-chain.hpp b/ndn-cxx/security/key-chain.hpp
index 55da405..9257606 100644
--- a/ndn-cxx/security/key-chain.hpp
+++ b/ndn-cxx/security/key-chain.hpp
@@ -239,7 +239,7 @@
public: // signing
/**
- * @brief Sign a Data packet according to the supplied signing information
+ * @brief Sign a Data packet according to the supplied signing information.
*
* This method uses the supplied signing information in @p params to sign @p data as follows:
* - It selects a private key and its associated certificate to sign the packet.
@@ -261,7 +261,7 @@
sign(Data& data, const SigningInfo& params = SigningInfo());
/**
- * @brief Sign an Interest according to the supplied signing information
+ * @brief Sign an Interest according to the supplied signing information.
*
* This method uses the supplied signing information in @p params to sign @p interest as follows:
* - It selects a private key and its associated certificate to sign the packet.
@@ -277,7 +277,6 @@
* element. Otherwise, it will be appended to the end of the name of @p interest as a
* SignatureValue block.
*
- *
* @param interest The interest to sign
* @param params The signing parameters
* @throw Error Signing failed
@@ -426,8 +425,8 @@
prepareSignatureInfo(const SigningInfo& params);
/**
- * @brief Generate a SignatureValue block for byte ranges in @p bufs using a key with name
- * @p keyName and digest algorithm @p digestAlgorithm.
+ * @brief Generate and return a raw signature for the byte ranges in @p bufs using
+ * the specified key and digest algorithm.
*/
ConstBufferPtr
sign(const InputBuffers& bufs, const Name& keyName, DigestAlgorithm digestAlgorithm) const;