cmake: build with -Wdocumentation

test/CMakeLists.txt

@@ -1,4 +1,4 @@
-cmake_minimum_required(VERSION 3.0)
+cmake_minimum_required(VERSION 3.0...3.5)
 project(SDL2_test)
 
 include(CheckCCompilerFlag)
@@ -20,6 +20,32 @@ macro(add_sdl_test_executable TARGET)
     if(AST_NEEDS_RESOURCES)
         list(APPEND SDL_TESTS_NEEDS_ESOURCES ${TARGET})
     endif()
+
+    if(HAVE_GCC_WDOCUMENTATION)
+        target_compile_options(${TARGET} PRIVATE "-Wdocumentation")
+        if(HAVE_GCC_WERROR_DOCUMENTATION)
+            target_compile_options(${TARGET} PRIVATE "-Werror=documentation")
+        endif()
+    endif()
+
+    if(HAVE_GCC_WDOCUMENTATION_UNKNOWN_COMMAND)
+        if(SDL_WERROR)
+            if(HAVE_GCC_WERROR_DOCUMENTATION_UNKNOWN_COMMAND)
+                target_compile_options(${TARGET} PRIVATE "-Werror=documentation-unknown-command")
+            endif()
+        endif()
+        target_compile_options(${TARGET} PRIVATE "-Wdocumentation-unknown-command")
+    endif()
+
+    if(HAVE_GCC_COMMENT_BLOCK_COMMANDS)
+        target_compile_options(${TARGET} PRIVATE "-fcomment-block-commands=threadsafety")
+        target_compile_options(${TARGET} PRIVATE "-fcomment-block-commands=deprecated")
+    else()
+        if(HAVE_CLANG_COMMENT_BLOCK_COMMANDS)
+            target_compile_options(${TARGET} PRIVATE "/clang:-fcomment-block-commands=threadsafety")
+            target_compile_options(${TARGET} PRIVATE "/clang:-fcomment-block-commands=deprecated")
+        endif()
+    endif()
 endmacro()
 
 if(NOT TARGET SDL2::SDL2-static)

test/testautomation_math.c

@@ -64,10 +64,10 @@ typedef double(SDLCALL *dd_to_d_func)(double, double);
  * \brief Runs all the cases on a given function with a signature double -> double.
  * The result is expected to be exact.
  *
- * \param func_name, a printable name for the tested function.
- * \param func, the function to call.
- * \param cases, an array of all the cases.
- * \param cases_size, the size of the cases array.
+ * \param func_name a printable name for the tested function.
+ * \param func the function to call.
+ * \param cases an array of all the cases.
+ * \param cases_size the size of the cases array.
  */
 static int
 helper_dtod(const char *func_name, d_to_d_func func,
@@ -90,10 +90,10 @@ helper_dtod(const char *func_name, d_to_d_func func,
  * \brief Runs all the cases on a given function with a signature double -> double.
  * Checks if the result between expected +/- EPSILON.
  *
- * \param func_name, a printable name for the tested function.
- * \param func, the function to call.
- * \param cases, an array of all the cases.
- * \param cases_size, the size of the cases array.
+ * \param func_name a printable name for the tested function.
+ * \param func the function to call.
+ * \param cases an array of all the cases.
+ * \param cases_size the size of the cases array.
  */
 static int
 helper_dtod_inexact(const char *func_name, d_to_d_func func,
@@ -119,10 +119,10 @@ helper_dtod_inexact(const char *func_name, d_to_d_func func,
  * \brief Runs all the cases on a given function with a signature
  * (double, double) -> double. The result is expected to be exact.
  *
- * \param func_name, a printable name for the tested function.
- * \param func, the function to call.
- * \param cases, an array of all the cases.
- * \param cases_size, the size of the cases array.
+ * \param func_name a printable name for the tested function.
+ * \param func the function to call.
+ * \param cases an array of all the cases.
+ * \param cases_size the size of the cases array.
  */
 static int
 helper_ddtod(const char *func_name, dd_to_d_func func,
@@ -145,10 +145,10 @@ helper_ddtod(const char *func_name, dd_to_d_func func,
  * \brief Runs all the cases on a given function with a signature
  * (double, double) -> double. Checks if the result between expected +/- EPSILON.
  *
- * \param func_name, a printable name for the tested function.
- * \param func, the function to call.
- * \param cases, an array of all the cases.
- * \param cases_size, the size of the cases array.
+ * \param func_name a printable name for the tested function.
+ * \param func the function to call.
+ * \param cases an array of all the cases.
+ * \param cases_size the size of the cases array.
  */
 static int
 helper_ddtod_inexact(const char *func_name, dd_to_d_func func,
@@ -176,8 +176,8 @@ helper_ddtod_inexact(const char *func_name, dd_to_d_func func,
  * This function is only meant to test functions that returns the input value if it is
  * integral: f(x) -> x for x in N.
  *
- * \param func_name, a printable name for the tested function.
- * \param func, the function to call.
+ * \param func_name a printable name for the tested function.
+ * \param func the function to call.
  */
 static int
 helper_range(const char *func_name, d_to_d_func func)

test/testautomation_render.c

@@ -1043,7 +1043,7 @@ _hasTexAlpha(void)
 /**
  * @brief Compares screen pixels with image pixels. Helper function.
  *
- * @param s Image to compare against.
+ * @param referenceSurface Image to compare against.
  *
  * \sa
  * http://wiki.libsdl.org/SDL_RenderReadPixels