Fix a bunch of docstrings
Clang correctly notes that a bunch of our docstrings are wrong. We
don't really use doxygen, but it's useful to be able to run a compiler
without warnings. The failures fall into a couple categories.
First, when using variadic templates, the type is the variable name (ie
T), not including variadic expansion. (ie T...). In these cases, the
... is removed from the definition.
Templatized structs should not use the @struct keyword. They are a
template as far as doxygen is concerned, so remove the keyword.
A number of functions docstrings are just wrong in terms of argument
names, or whether or not they have return types.
Signed-off-by: Ed Tanous <edtanous@google.com>
Change-Id: Iab6f76b422a9568b7ad19d3f725a9c1b870784d9
diff --git a/include/sdbusplus/asio/connection.hpp b/include/sdbusplus/asio/connection.hpp
index 2bb4880..444f79d 100644
--- a/include/sdbusplus/asio/connection.hpp
+++ b/include/sdbusplus/asio/connection.hpp
@@ -76,7 +76,8 @@
* upon return and return
*
* @param[in] m - A message ready to send
- * @param[in] token- The completion token to execute upon completion;
+ * @param[in] token - The completion token to execute upon completion;
+ * @param[in] timeout - The timeout in microseconds
*
*/
template <typename CompletionToken>
@@ -105,12 +106,8 @@
* @param[in] method - The object's method to call.
* @param[in] timeout - The timeout for the method call in usec (0 results
* in using the default value).
- * @param[in] a... - Optional parameters for the method call.
+ * @param[in] a - Optional parameters for the method call.
*
- * @return immediate return of the internal handler registration. The
- * result of the actual asynchronous call will get unpacked from
- * the message and passed into the handler when the call is
- * complete.
*/
template <typename MessageHandler, typename... InputArgs>
void async_method_call_timed(MessageHandler&& handler,
@@ -197,12 +194,8 @@
* @param[in] objpath - The object's path for the call.
* @param[in] interf - The object's interface to call.
* @param[in] method - The object's method to call.
- * @param[in] a... - Optional parameters for the method call.
+ * @param[in] a - Optional parameters for the method call.
*
- * @return immediate return of the internal handler registration. The
- * result of the actual asynchronous call will get unpacked from
- * the message and passed into the handler when the call is
- * complete.
*/
template <typename MessageHandler, typename... InputArgs>
void async_method_call(MessageHandler&& handler, const std::string& service,
@@ -224,7 +217,7 @@
* @param[in] objpath - The object's path for the call.
* @param[in] interf - The object's interface to call.
* @param[in] method - The object's method to call.
- * @param[in] a... - Optional parameters for the method call.
+ * @param[in] a - Optional parameters for the method call.
*
* @return Unpacked value of RetType
*/
diff --git a/include/sdbusplus/message.hpp b/include/sdbusplus/message.hpp
index b049a8f..ad9cef8 100644
--- a/include/sdbusplus/message.hpp
+++ b/include/sdbusplus/message.hpp
@@ -135,7 +135,7 @@
/** @brief Perform sd_bus_message_append, with automatic type deduction.
*
- * @tparam ...Args - Type of items to append to message.
+ * @tparam Args - Type of items to append to message.
* @param[in] args - Items to append to message.
*/
template <typename... Args>
@@ -147,7 +147,7 @@
/** @brief Perform sd_bus_message_read, with automatic type deduction.
*
- * @tparam ...Args - Type of items to read from message.
+ * @tparam Args - Type of items to read from message.
* @param[out] args - Items to read from message.
*/
template <typename... Args>
@@ -159,7 +159,7 @@
/** @brief Perform sd_bus_message_read with results returned.
*
- * @tparam ...Args - Type of items to read from the message.
+ * @tparam Args - Type of items to read from the message.
* @return One of { void, Args, std::tuple<Args...> }.
*/
template <typename... Args>
@@ -412,8 +412,7 @@
* in a METHOD_ERROR. This means you do not need to check
* is_method_error() on the returned message.
*
- * @param[in] m - The method_call message.
- * @param[in] timeout_us - The timeout for the method call.
+ * @param[in] timeout - The timeout for the method call.
*
* @return The response message.
*/
@@ -434,7 +433,7 @@
/** @brief Perform an async message call.
*
* @param[in] cb - The callback to run when the response is available.
- * @param[in] timeout_us - The timeout for the method call.
+ * @param[in] timeout - The timeout for the method call.
*
* @return The slot handle that manages the lifetime of the call object.
*/
diff --git a/include/sdbusplus/message/append.hpp b/include/sdbusplus/message/append.hpp
index dd002a5..e695b6f 100644
--- a/include/sdbusplus/message/append.hpp
+++ b/include/sdbusplus/message/append.hpp
@@ -27,7 +27,7 @@
{}
/** @brief Append data into an sdbus message.
*
- * @param[in] msg - The message to append to.
+ * @param[in] m - The message to append to.
* @tparam Args - C++ types of arguments to append to message.
* @param[in] args - values to append to message.
*
@@ -42,8 +42,7 @@
namespace details
{
-/** @struct can_append_multiple
- * @brief Utility to identify C++ types that may not be grouped into a
+/** @brief Utility to identify C++ types that may not be grouped into a
* single sd_bus_message_append call and instead need special
* handling.
*
@@ -99,8 +98,7 @@
inline constexpr bool can_append_multiple_v =
can_append_multiple<Args...>::value;
-/** @struct append_single
- * @brief Utility to append a single C++ element into a sd_bus_message.
+/** @brief Utility to append a single C++ element into a sd_bus_message.
*
* User-defined types are expected to specialize this template in order to
* get their functionality.
diff --git a/include/sdbusplus/message/read.hpp b/include/sdbusplus/message/read.hpp
index 066be20..4fb501d 100644
--- a/include/sdbusplus/message/read.hpp
+++ b/include/sdbusplus/message/read.hpp
@@ -27,7 +27,7 @@
inline void read(sdbusplus::SdBusInterface* /*intf*/, sd_bus_message* /*m*/) {}
/** @brief Read data from an sdbus message.
*
- * @param[in] msg - The message to read from.
+ * @param[in] m - The message to read from.
* @tparam Args - C++ types of arguments to read from message.
* @param[out] args - References to place contents read from message.
*
@@ -42,8 +42,7 @@
namespace details
{
-/** @struct can_read_multiple
- * @brief Utility to identify C++ types that may not be grouped into a
+/** @brief Utility to identify C++ types that may not be grouped into a
* single sd_bus_message_read call and instead need special
* handling.
*
@@ -103,8 +102,7 @@
template <typename... Args>
inline constexpr bool can_read_multiple_v = can_read_multiple<Args...>::value;
-/** @struct read_single
- * @brief Utility to read a single C++ element from a sd_bus_message.
+/** @brief Utility to read a single C++ element from a sd_bus_message.
*
* User-defined types are expected to specialize this template in order to
* get their functionality.
diff --git a/include/sdbusplus/message/types.hpp b/include/sdbusplus/message/types.hpp
index 60c87cc..faaf23a 100644
--- a/include/sdbusplus/message/types.hpp
+++ b/include/sdbusplus/message/types.hpp
@@ -26,7 +26,7 @@
* @brief Get a tuple containing the dbus type character(s) for a
* sequence of C++ types.
*
- * @tparam ...Args - Types to get the type_id sequence for.
+ * @tparam Args - Types to get the type_id sequence for.
* @returns A tuple of characters representing the dbus types for ...Args.
*
* The design uses a tuple because a tuple can, at compile-time, be easily
@@ -114,11 +114,10 @@
static constexpr auto value = std::make_tuple();
};
-/** @struct tuple_type_id
- * @brief Special type indicating a tuple of dbus-type_id's.
+/** @brief Special type indicating a tuple of dbus-type_id's.
*
* @tparam C1 - The first dbus type character character.
- * @tparam ...C - The remaining sequence of dbus type characters.
+ * @tparam C - The remaining sequence of dbus type characters.
*
* A tuple_type_id must be one or more characters. The C1 template param
* ensures at least one is present.
@@ -154,13 +153,12 @@
* C++ types.
*
* @tparam T - The first type to get the dbus type character(s) for.
- * @tparam ...Args - The remaining types.
+ * @tparam Args - The remaining types.
*/
template <typename T, typename... Args>
constexpr auto type_id_multiple();
-/** @struct type_id
- * @brief Defined dbus type tuple for a C++ type.
+/** @brief Defined dbus type tuple for a C++ type.
*
* @tparam T - C++ type.
*
diff --git a/include/sdbusplus/timer.hpp b/include/sdbusplus/timer.hpp
index 69cbcb2..526a050 100644
--- a/include/sdbusplus/timer.hpp
+++ b/include/sdbusplus/timer.hpp
@@ -25,7 +25,7 @@
/** @brief Constructs timer object
* Uses the default sd_event object
*
- * @param[in] funcCallBack - optional function callback for timer
+ * @param[in] userCallBack - optional function callback for timer
* expirations
*/
Timer(std::function<void()> userCallBack = nullptr) :
@@ -40,8 +40,8 @@
/** @brief Constructs timer object
*
- * @param[in] events - sd_event pointer
- * @param[in] funcCallBack - optional function callback for timer
+ * @param[in] event - sd_event pointer
+ * @param[in] userCallBack - optional function callback for timer
* expirations
*/
Timer(sd_event* event, std::function<void()> userCallBack = nullptr) :
@@ -156,8 +156,6 @@
/** @brief Initializes the timer object with infinite
* expiration time and sets up the callback handler
*
- * @return None.
- *
* @error std::runtime exception thrown
*/
void initialize()
@@ -207,10 +205,6 @@
*
* On getting the signal, initiate the hard power off request
*
- * @param[in] eventSource - Source of the event
- * @param[in] usec - time in micro seconds
- * @param[in] userData - User data pointer
- *
*/
int timeoutHandler()
{
diff --git a/include/sdbusplus/utility/merge_variants.hpp b/include/sdbusplus/utility/merge_variants.hpp
index 7079682..b8e18bb 100644
--- a/include/sdbusplus/utility/merge_variants.hpp
+++ b/include/sdbusplus/utility/merge_variants.hpp
@@ -31,7 +31,7 @@
/** Compute the merged variant type.
*
- * @tparam D, Done - Head and tail of the alternative types list of the
+ * @tparam D - Done - Head and tail of the alternative types list of the
* first variant.
* @tparam Next - The types of the next variant<...> to be merged with the
* first.
diff --git a/include/sdbusplus/utility/tuple_to_array.hpp b/include/sdbusplus/utility/tuple_to_array.hpp
index dfaf60a..bbabe70 100644
--- a/include/sdbusplus/utility/tuple_to_array.hpp
+++ b/include/sdbusplus/utility/tuple_to_array.hpp
@@ -21,7 +21,7 @@
* @tparam I - Sequence of integral indexes (0...N) for each tuple elemeent.
*
* @param tuple - Tuple of N same-typed elements.
- * @param [unnamed] - std::integer_sequence of tuple's index values.
+ * @param @exclude [unnamed] - std::integer_sequence of tuple's index values.
*
* @return A std::array where each I-th element is tuple's I-th element.
*/