clang: fix various documentation errors

Found with -Wdocumentation

Signed-off-by: Rosen Penev <rosenp@gmail.com>

include/exiv2/asfvideo.hpp

@@ -135,7 +135,6 @@ class EXIV2API AsfVideo : public Image {
   /*!
     @brief Interpret Content_Description tag information, and save it
         in the respective XMP container.
-    @param size Size of the data block used to store Tag Data.
    */
   void contentDescription();
   /*!

include/exiv2/bmffimage.hpp

@@ -60,6 +60,7 @@ class EXIV2API BmffImage : public Image {
   //@}
 
   //@{
+  void parseTiff(uint32_t root_tag, uint64_t length);
   /*!
     @brief parse embedded tiff file (Exif metadata)
     @param root_tag root of parse tree Tag::root, Tag::cmt2 etc.
@@ -67,7 +68,6 @@ class EXIV2API BmffImage : public Image {
     @param start offset in file (default, io_->tell())
    @
    */
-  void parseTiff(uint32_t root_tag, uint64_t length);
   void parseTiff(uint32_t root_tag, uint64_t length, uint64_t start);
   //@}
 

include/exiv2/futils.hpp

@@ -18,7 +18,7 @@ enum Protocol { pFile = 0, pHttp, pFtp, pHttps, pSftp, pFileUri, pDataUri, pStdi
 // free functions
 /*!
   @brief  Return the value of environmental variable.
-  @param[in]  var The name of environmental variable. Must be a member of the enumeration @ref EnVar.
+  @param[in]  env_var The name of environmental variable. Must be a member of the enumeration @ref EnVar.
   @return the value of environmental variable. If it's empty, the default value is returned.
   @throws std::out_of_range when an unexpected EnVar is given as input.
  */
@@ -74,7 +74,6 @@ EXIV2API Protocol fileProtocol(const std::string& path);
   @brief Test if a file exists.
 
   @param  path Name of file to verify.
-  @param  ct   Flag to check if <i>path</i> is a regular file.
   @return true if <i>path</i> exists and, if <i>ct</i> is set,
   is a regular file, else false.
 

include/exiv2/jp2image.hpp

@@ -68,16 +68,16 @@ class EXIV2API Jp2Image : public Image {
   /*!
     @brief Provides the main implementation of writeMetadata() by
           writing all buffered metadata to the provided BasicIo.
-    @param oIo BasicIo instance to write to (a temporary location).
+    @throw Error on input-output errors or when the image data is not valid.
+    @param outIo BasicIo instance to write to (a temporary location).
 
-    @return 4 if opening or writing to the associated BasicIo fails
    */
   void doWriteMetadata(BasicIo& outIo);
 
   /*!
    @brief reformats the Jp2Header to store iccProfile
-   @param oldData DataBufRef to data in the file.
+   @param boxBuf DataBufRef to data in the file.
-   @param newData DataBufRef with updated data
+   @param outBuf DataBufRef with updated data
    */
   void encodeJp2Header(const DataBuf& boxBuf, DataBuf& outBuf);
   //@}

include/exiv2/jpgimage.hpp

@@ -100,9 +100,9 @@ class EXIV2API JpegBase : public Image {
   /*!
     @brief Provides the main implementation of writeMetadata() by
           writing all buffered metadata to the provided BasicIo.
-    @param oIo BasicIo instance to write to (a temporary location).
+    @throw Error on input-output errors or when the image data is not valid.
+    @param outIo BasicIo instance to write to (a temporary location).
 
-    @return 4 if opening or writing to the associated BasicIo fails
    */
   void doWriteMetadata(BasicIo& outIo);
   //@}
@@ -164,7 +164,7 @@ class EXIV2API JpegImage : public JpegBase {
   //@{
   /*!
     @brief Writes a Jpeg header (aka signature) to the BasicIo instance.
-    @param oIo BasicIo instance that the header is written to.
+    @param outIo BasicIo instance that the header is written to.
     @return 0 if successful;<BR>
            2 if the input image is invalid or can not be read;<BR>
            4 if the temporary image can not be written to;<BR>

include/exiv2/matroskavideo.hpp

@@ -144,7 +144,7 @@ class EXIV2API MatroskaVideo : public Image {
   void decodeBlock();
   /*!
     @brief Interpret tag information, and save it in the respective XMP container.
-    @param mt Pointer to current tag,
+    @param tag Pointer to current tag,
     @param buf Pointer to the memory area with the tag information.
     @param size Size of \em buf.
    */

include/exiv2/pgfimage.hpp

@@ -59,9 +59,9 @@ class EXIV2API PgfImage : public Image {
   /*!
     @brief Provides the main implementation of writeMetadata() by
           writing all buffered metadata to the provided BasicIo.
-    @param oIo BasicIo instance to write to (a temporary location).
+    @throw Error on input-output errors or when the image data is not valid.
+    @param outIo BasicIo instance to write to (a temporary location).
 
-    @return 4 if opening or writing to the associated BasicIo fails
    */
   void doWriteMetadata(BasicIo& outIo);
   //! Read Magick number. Only version >= 6 is supported.

include/exiv2/pngimage.hpp

@@ -65,7 +65,7 @@ class EXIV2API PngImage : public Image {
     @brief Provides the main implementation of writeMetadata() by
           writing all buffered metadata to the provided BasicIo.
     @throw Error on input-output errors or when the image data is not valid.
-    @param oIo BasicIo instance to write to (a temporary location).
+    @param outIo BasicIo instance to write to (a temporary location).
 
    */
   void doWriteMetadata(BasicIo& outIo);

include/exiv2/psdimage.hpp

@@ -70,9 +70,9 @@ class EXIV2API PsdImage : public Image {
   /*!
     @brief Provides the main implementation of writeMetadata() by
           writing all buffered metadata to the provided BasicIo.
+    @throw Error on input-output errors or when the image data is not valid.
     @param outIo BasicIo instance to write to (a temporary location).
 
-    @return 4 if opening or writing to the associated BasicIo fails
    */
   void doWriteMetadata(BasicIo& outIo);
   uint32_t writeExifData(const ExifData& exifData, BasicIo& out);

include/exiv2/riffvideo.hpp

@@ -70,7 +70,6 @@ class EXIV2API RiffVideo : public Image {
 
   /*!
   @brief Interpret MainAVIHeader (avih) structure, and save it in the respective XMP container.
-  @param size Size of the data block used to store Tag Information.
   */
   void readAviHeader();
 
@@ -81,52 +80,52 @@ class EXIV2API RiffVideo : public Image {
 
   /*!
   @brief Interpret stream header list element (strf), and save it in the respective XMP container.
-  @param size Size of the data block used to store Tag Information.
+  @param size_ Size of the data block used to store Tag Information.
   */
   void readStreamFormat(uint64_t size_);
 
   /*!
   @brief Interpret Additional header data (strd), and save it in the respective XMP container.
-  @param size Size of the data block used to store Tag Information.
+  @param size_ Size of the data block used to store Tag Information.
  */
   void readStreamData(uint64_t size_);
 
   /*!
   @brief Interpret stream header list element (strn) , and save it in the respective XMP container.
-  @param size Size of the data block used to store Tag Information.
+  @param size_ Size of the data block used to store Tag Information.
  */
   void StreamName(uint64_t size_);
   /*!
   @brief Interpret INFO List Chunk, and save it in the respective XMP container.
-  @param size Size of the data block used to store Tag Information.
+  @param size_ Size of the data block used to store Tag Information.
  */
   void readInfoListChunk(uint64_t size_);
 
   /*!
   @brief Interpret Riff Stream Data tag information, and save it in the respective XMP container.
   The Movi - Lists contain Video, Audio, Subtitle and (secondary) index data. Those can be grouped into rec - Lists.
-  @param size Size of the data block used to store Tag Information.
+  @param size_ Size of the data block used to store Tag Information.
  */
   void readMoviList(uint64_t size_);
   /*!
   @brief Interpret Video Properties Header chunk, and save it in the respective XMP container.
   The video properties header identifies video signal properties associated with a digital video stream in an AVI file
-  @param size Size of the data block used to store Tag Information.
+  @param size_ Size of the data block used to store Tag Information.
  */
   void readVPRPChunk(uint64_t size_);
   /*!
   @brief Interpret Riff INdex Chunk, and save it in the respective XMP container.
-  @param size Size of the data block used to store Tag Information.
+  @param size_ Size of the data block used to store Tag Information.
  */
   void readIndexChunk(uint64_t size_);
   /*!
   @brief Interpret Riff Stream Chunk, and save it in the respective XMP container.
-  @param size Size of the data block used to store Tag Information.
+  @param size_ Size of the data block used to store Tag Information.
  */
   void readDataChunk(uint64_t size_);
   /*!
   @brief Interpret Junk Chunk and save it in the respective XMP container.
-  @param size Size of the data block used to store Tag Information.
+  @param size_ Size of the data block used to store Tag Information.
  */
   void readJunk(uint64_t size_);
 

include/exiv2/types.hpp

@@ -215,10 +215,12 @@ struct EXIV2API DataBuf {
 /*!
  * @brief Create a new Slice from a DataBuf given the bounds.
  *
- * @param[in] begin, end  Bounds of the new Slice. `begin` must be smaller
- *     than `end` and both must not be larger than LONG_MAX.
  * @param[in] buf  The DataBuf from which' data the Slice will be
  *     constructed
+ * @param[in] begin Beginning bound of the new Slice. Must be smaller
+ *     than `end` and both must not be larger than LONG_MAX.
+ * @param[in] end End bound of the new Slice. Must be smaller
+ *     than `end` and both must not be larger than LONG_MAX.
  *
  * @throw std::invalid_argument when `end` is larger than `LONG_MAX` or
  * anything that the constructor of @ref Slice throws

src/convert.cpp

@@ -273,7 +273,7 @@ class Converter {
   std::string computeExifDigest(bool tiff);
 
   // DATA
-  static const Conversion conversion_[];  //<! Conversion rules
+  static const Conversion conversion_[];  ///< Conversion rules
   bool erase_{false};
   bool overwrite_{true};
   ExifData* exifData_;

src/jp2image_int.hpp

@@ -17,10 +17,10 @@ struct Jp2ImageHeaderBox {
   uint32_t imageHeight;
   uint32_t imageWidth;
   uint16_t componentCount;
-  uint8_t bpc;   //<! Bits per component
+  uint8_t bpc;   ///< Bits per component
-  uint8_t c;     //<! Compression type
+  uint8_t c;     ///< Compression type
-  uint8_t unkC;  //<! Colourspace unknown
+  uint8_t unkC;  ///< Colourspace unknown
-  uint8_t ipr;   //<! Intellectual property
+  uint8_t ipr;   ///< Intellectual property
 };
 
 struct Jp2UuidBox {

src/makernote_int.hpp

@@ -85,8 +85,8 @@ class TiffMnCreator {
   TiffMnCreator& operator=(const TiffComponent&) = delete;
 
  private:
-  static const TiffMnRegistry registry_[];  //<! List of makernotes
+  static const TiffMnRegistry registry_[];  ///< List of makernotes
-};                                          // class TiffMnCreator
+};
 
 //! Makernote header interface. This class is used with TIFF makernotes.
 class MnHeader {

src/orfimage_int.hpp

@@ -35,8 +35,8 @@ class OrfHeader : public TiffHeaderBase {
   //@}
  private:
   // DATA
-  uint16_t sig_{0x4f52};  //<! The actual magic number
+  uint16_t sig_{0x4f52};  ///< The actual magic number
-};                        // class OrfHeader
+};
 
 }  // namespace Exiv2::Internal
 

src/safe_op.hpp

@@ -48,7 +48,8 @@ namespace Internal {
  *
  * @return true on overflow, false on no overflow
  *
- * @param[in] summand_1, summand_2 The summands with are added
+ * @param[in] summand_1 The summand with is added
+ * @param[in] summand_2 The summand with is added
  * @param[out] result Result of the addition, only populated when no
  * overflow occurs.
  *
@@ -139,7 +140,8 @@ SPECIALIZE_builtin_add_overflow(unsigned long long, __builtin_uaddll_overflow);
  * operation would not overflow, otherwise an exception of type
  * std::overflow_error is thrown.
  *
- * @param[in] summand_1, summand_2  summands to be summed up
+ * @param[in] summand_1 summand to be summed up
+ * @param[in] summand_2 summand to be summed up
  * @return  the sum of summand_1 and summand_2
  * @throws  std::overflow_error if the addition would overflow
  *

src/tiffimage_int.hpp

@@ -173,8 +173,8 @@ class TiffCreator {
   static TiffPath getPath(uint32_t extendedTag, IfdId group, uint32_t root);
 
  private:
-  static const TiffTreeTable tiffTreeTable_;    //<! TIFF tree structure
+  static const TiffTreeTable tiffTreeTable_;    ///< TIFF tree structure
-  static const TiffGroupTable tiffGroupTable_;  //<! TIFF group structure
+  static const TiffGroupTable tiffGroupTable_;  ///< TIFF group structure
 
 };  // class TiffCreator
 
@@ -241,8 +241,8 @@ class TiffParserWorker {
     @brief Find primary groups in the source tree provided and populate
            the list of primary groups.
 
-    @param primaryGroups List of primary groups which is populated
     @param pSourceDir Pointer to the source composite tree to search (may be 0)
+    @return List of primary groups which is populated
    */
   static PrimaryGroups findPrimaryGroups(TiffComponent* pSourceDir);
 
@@ -286,7 +286,7 @@ class TiffMapping {
   static EncoderFct findEncoder(const std::string& make, uint32_t extendedTag, IfdId group);
 
  private:
-  static const TiffMappingInfo tiffMappingInfo_[];  //<! TIFF mapping table
+  static const TiffMappingInfo tiffMappingInfo_[];  ///< TIFF mapping table
 
 };  // class TiffMapping
 

src/tiffvisitor_int.hpp

@@ -197,7 +197,7 @@ class TiffCopier : public TiffVisitor {
     @brief Constructor
 
     @param pRoot Pointer to the root element of the (empty) target tree.
-    @param root
+    @param root Actual root element
     @param pHeader Pointer to the TIFF header of the source image.
     @param pPrimaryGroups Pointer to the list of primary groups.
    */

src/webpimage.cpp

@@ -724,7 +724,6 @@ bool WebPImage::equalsWebPTag(const Exiv2::DataBuf& buf, const char* str) {
  @param  iIo get BasicIo pointer to inject data
  @param has_xmp Verify if we have xmp data and set required flag
  @param has_exif Verify if we have exif data and set required flag
- @return Returns void
  */
 void WebPImage::inject_VP8X(BasicIo& iIo, bool has_xmp, bool has_exif, bool has_alpha, bool has_icc, uint32_t width,
                             uint32_t height) const {