Enable -Wdocumentation and fix issues

cmake/AISClangCompilerOptions.cmake

@@ -35,7 +35,7 @@ function(get_ais_clang_warning_flags outvar compiler_version)
         -Wthread-safety
 
         # Turn this on later (generates a lot of noise now)
-        #-Wdocumentation
+        -Wdocumentation
 
         # Avoid things that will cause problems on Windows
         -Wmicrosoft

rocfile/src/backend.h

@@ -38,7 +38,7 @@ struct Backend {
     /// @param size           The IO request's size
     /// @param file_offset    Offset from the start of the file
     /// @param buffer_offset  Offset from the start of the buffer
-    /// @return
+    /// @return The eagerness "score"
     virtual int score(std::shared_ptr<IFile> file, std::shared_ptr<IBuffer> buffer, size_t size,
                       hoff_t file_offset, hoff_t buffer_offset) const = 0;
 

rocfile/src/batch/batch.h

@@ -70,8 +70,8 @@ class BatchContext : public IBatchContext {
 
     ///
     /// @brief Submit one or more operations to this Context.
-    /// @param [in] ops Pointer to the operations to enqueue.
-    /// @param [in] num_ops Number of operations to enqueue.
+    /// @param [in] params     Pointer to the operations to enqueue.
+    /// @param [in] num_params Number of operations to enqueue.
     ///
     /// @note This is an All or None operation. If one submitted operation is not valid, no operations
     ///       will be submitted.
@@ -107,13 +107,13 @@ class BatchContextMap {
 
     /*!
      * @brief Destroy a batch context and release all associated resources
-     * @param batch_handle The handle for the batch context to destroy
+     * @param handle The handle for the batch context to destroy
      */
     void destroyContext(rocFileBatchHandle_t handle);
 
     /*!
      * @brief Get a batch context
-     * @param  batch_handle The opaque handle associated with a batch context
+     * @param handle The opaque handle associated with a batch context
      * @return A batch context
      */
     std::shared_ptr<IBatchContext> get(rocFileBatchHandle_t handle);

rocfile/src/context.h

@@ -41,7 +41,7 @@ template <typename T> struct Context {
 
 private:
     /// @brief Set a context to temporarily override the default
-    /// @param _current A pointer to the new context
+    /// @param _replacement A pointer to the replacement context
     static void override(T *_replacement)
     {
         std::lock_guard<std::mutex> lock{m};

rocfile/src/state.h

@@ -160,9 +160,7 @@ class DriverState {
     /// Like the buffer getter, this function emits a temporary unregistered buffer
     /// (of size length, using flags) if no matching buffer is found.
     ///
-    /// @param [out] outFile File object
     /// @param [in]  fh      File handle
-    /// @param [out] outBuf  Registered or temporary unregistered Buffer object
     /// @param [in]  buf     Buffer pointer
     /// @param [in]  length  Buffer length
     /// @param [in]  flags   Buffer flags (unused)