[docs] Fix Doxygen warnings, add CI docs lint job (#3639)

The CI docs lint build is configured to fail on Doxygen warnings.

wpiutil/src/main/native/include/wpi/HttpServerConnection.h

@@ -35,7 +35,7 @@ class HttpServerConnection {
    * Build common response headers.
    *
    * Called by SendHeader() to send headers common to every response.
-   * Each line must be terminated with \r\n.
+   * Each line must be terminated with "\r\n".
    *
    * The default implementation sends the following:
    * "Server: WebServer/1.0\r\n"

wpiutil/src/main/native/include/wpi/SafeThread.h

@@ -15,7 +15,9 @@
 
 namespace wpi {
 
-// Base class for SafeThreadOwner threads.
+/**
+ * Base class for SafeThreadOwner threads.
+ */
 class SafeThread {
  public:
   virtual ~SafeThread() = default;
@@ -29,7 +31,9 @@ class SafeThread {
 
 namespace detail {
 
-// Non-template proxy base class for common proxy code.
+/**
+ * Non-template proxy base class for common proxy code.
+ */
 class SafeThreadProxyBase {
  public:
   explicit SafeThreadProxyBase(std::shared_ptr<SafeThread> thr);
@@ -41,8 +45,11 @@ class SafeThreadProxyBase {
   std::unique_lock<wpi::mutex> m_lock;
 };
 
-// A proxy for SafeThread.
-// Also serves as a scoped lock on SafeThread::m_mutex.
+/**
+ * A proxy for SafeThread.
+ *
+ * Also serves as a scoped lock on SafeThread::m_mutex.
+ */
 template <typename T>
 class SafeThreadProxy : public SafeThreadProxyBase {
  public:
@@ -52,7 +59,9 @@ class SafeThreadProxy : public SafeThreadProxyBase {
   T* operator->() const { return static_cast<T*>(m_thread.get()); }
 };
 
-// Non-template owner base class for common owner code.
+/**
+ * Non-template owner base class for common owner code.
+ */
 class SafeThreadOwnerBase {
  public:
   void Stop();

wpiutil/src/main/native/include/wpi/Signal.h

@@ -565,7 +565,7 @@ public:
      *         signal object, it does not cover thread safety of potentially
      *         shared state used in slot functions.
      *
-     * @param a... arguments to emit
+     * @param a arguments to emit
      */
     template <typename... A>
     void operator()(A && ... a) const {
@@ -581,7 +581,6 @@ public:
      * Safety: Thread-safety depends on locking policy.
      *
      * @param c a callable
-     * @return a Connection object that can be used to interact with the slot
      */
     template <typename Callable>
     void connect(Callable && c) {

wpiutil/src/main/native/include/wpi/UidVector.h

@@ -60,12 +60,15 @@ class UidVectorIterator {
 };
 }  // namespace impl
 
-// Vector which provides an integrated freelist for removal and reuse of
-// individual elements.
-// @tparam T element type; must be default-constructible and evaluate in
-//           boolean context to false when "empty"
-// @tparam reuse_threshold how many free elements to store up before starting
-//                         to recycle them
+/**
+ * Vector which provides an integrated freelist for removal and reuse of
+ * individual elements.
+ *
+ * @tparam T element type; must be default-constructible and evaluate in
+ *           boolean context to false when "empty"
+ * @tparam reuse_threshold how many free elements to store up before starting
+ *                         to recycle them
+ */
 template <typename T, typename std::vector<T>::size_type reuse_threshold>
 class UidVector {
  public:
@@ -103,8 +106,10 @@ class UidVector {
     return uid;
   }
 
-  // Removes the identified element by replacing it with a default-constructed
-  // one.  The element is added to the freelist for later reuse.
+  /**
+   * Removes the identified element by replacing it with a default-constructed
+   * one. The element is added to the freelist for later reuse.
+   */
   T erase(size_type uid) {
     if (uid >= m_vector.size() || !m_vector[uid]) {
       return T();
@@ -116,7 +121,9 @@ class UidVector {
     return rv;
   }
 
-  // Removes all elements.
+  /**
+   * Removes all elements.
+   */
   void clear() noexcept {
     m_vector.clear();
     m_free.clear();

wpiutil/src/main/native/include/wpi/WorkerThread.h

@@ -225,6 +225,7 @@ class WorkerThread<R(T...)> final {
    * destroyed while waiting for a result.
    *
    * @param work Work function (called on worker thread)
+   * @param u Arguments to work function
    */
   template <typename... U>
   future<R> QueueWork(WorkFunction work, U&&... u) {
@@ -260,6 +261,7 @@ class WorkerThread<R(T...)> final {
    *
    * @param work Work function (called on worker thread)
    * @param afterWork After work function (called on loop thread)
+   * @param u Arguments to work function
    */
   template <typename... U>
   void QueueWorkThen(WorkFunction work, AfterWorkFunction afterWork, U&&... u) {

wpiutil/src/main/native/include/wpi/jni_util.h

@@ -26,15 +26,27 @@
 /** Java Native Interface (JNI) utility functions */
 namespace wpi::java {
 
-// Gets a Java stack trace.  Also provides the last function
-// in the stack trace not starting with excludeFuncPrefix (useful for e.g.
-// finding the first user call to a series of library functions).
+/**
+ * Gets a Java stack trace.
+ *
+ * Also provides the last function in the stack trace not starting with
+ * excludeFuncPrefix (useful for e.g. finding the first user call to a series of
+ * library functions).
+ *
+ * @param env JRE environment.
+ * @param func Storage for last function in the stack trace not starting with
+ *             excludeFuncPrefix.
+ * @param excludeFuncPrefix Prefix for functions to ignore in stack trace.
+ */
 std::string GetJavaStackTrace(JNIEnv* env, std::string* func = nullptr,
                               std::string_view excludeFuncPrefix = {});
 
-// Finds a class and keep it as a global reference.
-// Use with caution, as the destructor does NOT call DeleteGlobalRef due
-// to potential shutdown issues with doing so.
+/**
+ * Finds a class and keeps it as a global reference.
+ *
+ * Use with caution, as the destructor does NOT call DeleteGlobalRef due to
+ * potential shutdown issues with doing so.
+ */
 class JClass {
  public:
   JClass() = default;
@@ -92,8 +104,11 @@ class JGlobal {
   T m_cls = nullptr;
 };
 
-// Container class for cleaning up Java local references.
-// The destructor calls DeleteLocalRef.
+/**
+ * Container class for cleaning up Java local references.
+ *
+ * The destructor calls DeleteLocalRef.
+ */
 template <typename T>
 class JLocal {
  public:
@@ -126,9 +141,12 @@ class JLocal {
 // Conversions from Java objects to C++
 //
 
-// Java string (jstring) reference.  The string is provided as UTF8.
-// This is not actually a reference, as it makes a copy of the string
-// characters, but it's named this way for consistency.
+/**
+ * Java string (jstring) reference.
+ *
+ * The string is provided as UTF8. This is not actually a reference, as it makes
+ * a copy of the string characters, but it's named this way for consistency.
+ */
 class JStringRef {
  public:
   JStringRef(JNIEnv* env, jstring str) {
@@ -163,7 +181,9 @@ namespace detail {
 template <typename C, typename T>
 class JArrayRefInner {};
 
-// Specialization of JArrayRefBase to provide std::string_view conversion.
+/**
+ * Specialization of JArrayRefBase to provide std::string_view conversion.
+ */
 template <typename C>
 class JArrayRefInner<C, jbyte> {
  public:
@@ -178,7 +198,9 @@ class JArrayRefInner<C, jbyte> {
   }
 };
 
-// Base class for J*ArrayRef and CriticalJ*ArrayRef
+/**
+ * Base class for J*ArrayRef and CriticalJ*ArrayRef
+ */
 template <typename T>
 class JArrayRefBase : public JArrayRefInner<JArrayRefBase<T>, T> {
  public:
@@ -329,7 +351,12 @@ WPI_JNI_JARRAYREF(jdouble, Double)
 // Conversions from C++ to Java objects
 //
 
-// Convert a UTF8 string into a jstring.
+/**
+ * Convert a UTF8 string into a jstring.
+ *
+ * @param env JRE environment.
+ * @param str String to convert.
+ */
 inline jstring MakeJString(JNIEnv* env, std::string_view str) {
   SmallVector<UTF16, 128> chars;
   convertUTF8ToUTF16String(str, chars);
@@ -339,9 +366,12 @@ inline jstring MakeJString(JNIEnv* env, std::string_view str) {
 // details for MakeJIntArray
 namespace detail {
 
-// Slow path (get primitive array and set individual elements).  This
-// is used if the input type is not an integer of the same size (note
-// signed/unsigned is ignored).
+/**
+ * Slow path (get primitive array and set individual elements).
+ *
+ * This is used if the input type is not an integer of the same size (note
+ * signed/unsigned is ignored).
+ */
 template <typename T,
           bool = (std::is_integral<T>::value && sizeof(jint) == sizeof(T))>
 struct ConvertIntArray {
@@ -363,7 +393,9 @@ struct ConvertIntArray {
   }
 };
 
-// Fast path (use SetIntArrayRegion)
+/**
+ * Fast path (use SetIntArrayRegion).
+ */
 template <typename T>
 struct ConvertIntArray<T, true> {
   static jintArray ToJava(JNIEnv* env, span<const T> arr) {
@@ -379,32 +411,62 @@ struct ConvertIntArray<T, true> {
 
 }  // namespace detail
 
-// Convert an span to a jintArray.
+/**
+ * Convert a span to a jintArray.
+ *
+ * @param env JRE environment.
+ * @param arr Span to convert.
+ */
 template <typename T>
 inline jintArray MakeJIntArray(JNIEnv* env, span<const T> arr) {
   return detail::ConvertIntArray<T>::ToJava(env, arr);
 }
 
+/**
+ * Convert a span to a jintArray.
+ *
+ * @param env JRE environment.
+ * @param arr Span to convert.
+ */
 template <typename T>
 inline jintArray MakeJIntArray(JNIEnv* env, span<T> arr) {
   return detail::ConvertIntArray<T>::ToJava(env, arr);
 }
 
-// Convert a SmallVector to a jintArray.  This is required in addition to
-// ArrayRef because template resolution occurs prior to implicit conversions.
+/**
+ * Convert a SmallVector to a jintArray.
+ *
+ * This is required in addition to ArrayRef because template resolution occurs
+ * prior to implicit conversions.
+ *
+ * @param env JRE environment.
+ * @param arr SmallVector to convert.
+ */
 template <typename T>
 inline jintArray MakeJIntArray(JNIEnv* env, const SmallVectorImpl<T>& arr) {
   return detail::ConvertIntArray<T>::ToJava(env, arr);
 }
 
-// Convert a std::vector to a jintArray.  This is required in addition to
-// ArrayRef because template resolution occurs prior to implicit conversions.
+/**
+ * Convert a std::vector to a jintArray.
+ *
+ * This is required in addition to ArrayRef because template resolution occurs
+ * prior to implicit conversions.
+ *
+ * @param env JRE environment.
+ * @param arr SmallVector to convert.
+ */
 template <typename T>
 inline jintArray MakeJIntArray(JNIEnv* env, const std::vector<T>& arr) {
   return detail::ConvertIntArray<T>::ToJava(env, arr);
 }
 
-// Convert a std::string_view into a jbyteArray.
+/**
+ * Convert a std::string_view into a jbyteArray.
+ *
+ * @param env JRE environment.
+ * @param str std::string_view to convert.
+ */
 inline jbyteArray MakeJByteArray(JNIEnv* env, std::string_view str) {
   jbyteArray jarr = env->NewByteArray(str.size());
   if (!jarr) {
@@ -415,7 +477,12 @@ inline jbyteArray MakeJByteArray(JNIEnv* env, std::string_view str) {
   return jarr;
 }
 
-// Convert an array of integers into a jbooleanArray.
+/**
+ * Convert an array of integers into a jbooleanArray.
+ *
+ * @param env JRE environment.
+ * @param arr Array to convert.
+ */
 inline jbooleanArray MakeJBooleanArray(JNIEnv* env, span<const int> arr) {
   jbooleanArray jarr = env->NewBooleanArray(arr.size());
   if (!jarr) {
@@ -433,7 +500,12 @@ inline jbooleanArray MakeJBooleanArray(JNIEnv* env, span<const int> arr) {
   return jarr;
 }
 
-// Convert an array of booleans into a jbooleanArray.
+/**
+ * Convert an array of booleans into a jbooleanArray.
+ *
+ * @param env JRE environment.
+ * @param arr Array to convert.
+ */
 inline jbooleanArray MakeJBooleanArray(JNIEnv* env, span<const bool> arr) {
   jbooleanArray jarr = env->NewBooleanArray(arr.size());
   if (!jarr) {
@@ -472,7 +544,12 @@ WPI_JNI_MAKEJARRAY(jdouble, Double)
 
 #undef WPI_JNI_MAKEJARRAY
 
-// Convert an array of std::string into a jarray of jstring.
+/**
+ * Convert an array of std::string into a jarray of jstring.
+ *
+ * @param env JRE environment.
+ * @param arr Array to convert.
+ */
 inline jobjectArray MakeJStringArray(JNIEnv* env, span<const std::string> arr) {
   static JClass stringCls{env, "java/lang/String"};
   if (!stringCls) {
@@ -489,21 +566,23 @@ inline jobjectArray MakeJStringArray(JNIEnv* env, span<const std::string> arr) {
   return jarr;
 }
 
-// Generic callback thread implementation.
-//
-// JNI's AttachCurrentThread() creates a Java Thread object on every
-// invocation, which is both time inefficient and causes issues with Eclipse
-// (which tries to keep a thread list up-to-date and thus gets swamped).
-//
-// Instead, this class attaches just once.  When a hardware notification
-// occurs, a condition variable wakes up this thread and this thread actually
-// makes the call into Java.
-//
-// The template parameter T is the message being passed to the callback, but
-// also needs to provide the following functions:
-//  static JavaVM* GetJVM();
-//  static const char* GetName();
-//  void CallJava(JNIEnv *env, jobject func, jmethodID mid);
+/**
+ * Generic callback thread implementation.
+ *
+ * JNI's AttachCurrentThread() creates a Java Thread object on every
+ * invocation, which is both time inefficient and causes issues with Eclipse
+ * (which tries to keep a thread list up-to-date and thus gets swamped).
+ *
+ * Instead, this class attaches just once.  When a hardware notification
+ * occurs, a condition variable wakes up this thread and this thread actually
+ * makes the call into Java.
+ *
+ * The template parameter T is the message being passed to the callback, but
+ * also needs to provide the following functions:
+ *  static JavaVM* GetJVM();
+ *  static const char* GetName();
+ *  void CallJava(JNIEnv *env, jobject func, jmethodID mid);
+ */
 template <typename T>
 class JCallbackThread : public SafeThread {
  public:
@@ -759,10 +838,13 @@ inline std::string GetJavaStackTrace(JNIEnv* env, std::string* func,
   return oss.str();
 }
 
-// Finds an exception class and keep it as a global reference.
-// Similar to JClass, but provides Throw methods.
-// Use with caution, as the destructor does NOT call DeleteGlobalRef due
-// to potential shutdown issues with doing so.
+/**
+ * Finds an exception class and keep it as a global reference.
+ *
+ * Similar to JClass, but provides Throw methods. Use with caution, as the
+ * destructor does NOT call DeleteGlobalRef due to potential shutdown issues
+ * with doing so.
+ */
 class JException : public JClass {
  public:
   JException() = default;

wpiutil/src/main/native/include/wpi/static_circular_buffer.h

@@ -82,17 +82,38 @@ class static_circular_buffer {
     size_t m_index;
   };
 
+  /**
+   * Returns begin iterator.
+   */
   iterator begin() { return iterator(this, 0); }
+
+  /**
+   * Returns end iterator.
+   */
   iterator end() {
     return iterator(this, ::wpi::static_circular_buffer<T, N>::size());
   }
 
+  /**
+   * Returns begin iterator.
+   */
   const_iterator begin() const { return const_iterator(this, 0); }
+
+  /**
+   * Returns end iterator.
+   */
   const_iterator end() const {
     return const_iterator(this, ::wpi::static_circular_buffer<T, N>::size());
   }
 
+  /**
+   * Returns begin iterator.
+   */
   const_iterator cbegin() const { return const_iterator(this, 0); }
+
+  /**
+   * Returns end iterator.
+   */
   const_iterator cend() const {
     return const_iterator(this, ::wpi::static_circular_buffer<T, N>::size());
   }