Merge GH #1132 Fix Doxygen errors and add -Wdocumentation flag to clang maintainer build

12 files changed, 14 insertions, 18 deletions

diff --git a/src/build-data/cc/clang.txt b/src/build-data/cc/clang.txt
index 2e6070390..2afd530d3 100644
--- a/src/build-data/cc/clang.txt
+++ b/src/build-data/cc/clang.txt
@@ -11,7 +11,7 @@ add_framework_option "-framework "
 lang_flags "-std=c++11 -D_REENTRANT"
 
 warning_flags "-Wall -Wextra -Wpedantic -Wshadow -Wstrict-aliasing -Wstrict-overflow=5 -Wcast-align -Wmissing-declarations -Wpointer-arith -Wcast-qual -Wunreachable-code"
-maintainer_warning_flags "-Qunused-arguments -Werror -Wno-error=unused-parameter -Wno-error=unused-variable -Wno-error=unreachable-code -Wno-error=deprecated-declarations"
+maintainer_warning_flags "-Wdocumentation -Qunused-arguments -Werror -Wno-error=unused-parameter -Wno-error=unused-variable -Wno-error=unreachable-code -Wno-error=deprecated-declarations"
 
 compile_flags "-c"
 debug_info_flags "-g"
diff --git a/src/lib/filters/pipe.h b/src/lib/filters/pipe.h
index 9be0fa1b4..1b839809d 100644
--- a/src/lib/filters/pipe.h
+++ b/src/lib/filters/pipe.h
@@ -181,7 +181,7 @@ class BOTAN_DLL Pipe final : public DataSource
       * @param msg the number identifying the message to read from
       * @return string holding the contents of the pipe
       */
-      std::string read_all_as_string(message_id = DEFAULT_MESSAGE) BOTAN_WARN_UNUSED_RESULT;
+      std::string read_all_as_string(message_id msg = DEFAULT_MESSAGE) BOTAN_WARN_UNUSED_RESULT;
 
       /**
       * Read from the default message but do not modify the internal
diff --git a/src/lib/math/numbertheory/pow_mod.h b/src/lib/math/numbertheory/pow_mod.h
index e7db774b6..50695c2bc 100644
--- a/src/lib/math/numbertheory/pow_mod.h
+++ b/src/lib/math/numbertheory/pow_mod.h
@@ -62,7 +62,7 @@ class BOTAN_DLL Power_Mod
       * representation. Likely only useful for testing.
       */
       void set_modulus(const BigInt& modulus,
-                       Usage_Hints = NO_HINTS,
+                       Usage_Hints hints = NO_HINTS,
                        bool disable_montgomery_arith = false) const;
 
       /**
diff --git a/src/lib/math/numbertheory/reducer.h b/src/lib/math/numbertheory/reducer.h
index 36808f00f..4de1e3d04 100644
--- a/src/lib/math/numbertheory/reducer.h
+++ b/src/lib/math/numbertheory/reducer.h
@@ -24,8 +24,8 @@ class BOTAN_DLL Modular_Reducer
 
       /**
       * Multiply mod p
-      * @param x
-      * @param y
+      * @param x the first operand
+      * @param y the second operand
       * @return (x * y) % p
       */
       BigInt multiply(const BigInt& x, const BigInt& y) const
@@ -33,7 +33,7 @@ class BOTAN_DLL Modular_Reducer
 
       /**
       * Square mod p
-      * @param x
+      * @param x the value to square
       * @return (x * x) % p
       */
       BigInt square(const BigInt& x) const
@@ -41,7 +41,7 @@ class BOTAN_DLL Modular_Reducer
 
       /**
       * Cube mod p
-      * @param x
+      * @param x the value to cube
       * @return (x * x * x) % p
       */
       BigInt cube(const BigInt& x) const
diff --git a/src/lib/prov/pkcs11/p11.cpp b/src/lib/prov/pkcs11/p11.cpp
index 8a460b66f..ab4784112 100644
--- a/src/lib/prov/pkcs11/p11.cpp
+++ b/src/lib/prov/pkcs11/p11.cpp
@@ -20,7 +20,7 @@ ReturnValue* ThrowException = reinterpret_cast< ReturnValue* >(-1);
 
 namespace {
 /// @param function_result Return value of the PKCS11 module function
-/// @param returnValue if (`ThrowException`) is passed the function throws an exception, otherwise if a non-NULL pointer is passed:
+/// @param return_value if (`ThrowException`) is passed the function throws an exception, otherwise if a non-NULL pointer is passed:
 /// return_value receives the return value of the PKCS#11 function and no exception is thrown.
 /// @return true if function call was successful, false otherwise
 bool handle_return_value(const CK_RV function_result, ReturnValue* return_value)
diff --git a/src/lib/prov/pkcs11/p11_rsa.h b/src/lib/prov/pkcs11/p11_rsa.h
index 1a6fd4890..f3ddd970b 100644
--- a/src/lib/prov/pkcs11/p11_rsa.h
+++ b/src/lib/prov/pkcs11/p11_rsa.h
@@ -190,7 +190,7 @@ class BOTAN_DLL PKCS11_RSA_PrivateKey final : public Private_Key,
 
       /**
       * Generates a PKCS#11 RSA private key
-      * @param session
+      * @param session the session to use
       * @param bits length in bits of modulus n
       * @param priv_key_props the properties of the RSA private key
       * @note no persistent public key object will be created
diff --git a/src/lib/pubkey/pubkey.h b/src/lib/pubkey/pubkey.h
index bfe444829..93eb07894 100644
--- a/src/lib/pubkey/pubkey.h
+++ b/src/lib/pubkey/pubkey.h
@@ -571,7 +571,7 @@ class BOTAN_DLL PK_Decryptor_EME final : public PK_Decryptor
       /**
       * Construct an instance.
       * @param key the key to use inside the decryptor
-      * @param padding the message encoding scheme to use (eg "OAEP(SHA-256)")
+      * @param eme the message encoding scheme to use (eg "OAEP(SHA-256)")
       */
       BOTAN_DEPRECATED("Use constructor taking a RNG object")
       PK_Decryptor_EME(const Private_Key& key,
diff --git a/src/lib/pubkey/xmss/xmss_address.h b/src/lib/pubkey/xmss/xmss_address.h
index 4ad30c3d9..8a53d4e80 100644
--- a/src/lib/pubkey/xmss/xmss_address.h
+++ b/src/lib/pubkey/xmss/xmss_address.h
@@ -218,8 +218,6 @@ class XMSS_Address
       /**
        * Set the chain address. A call to this method is only valid, if
        * the address type is set to Type::OTS_Hash_Address.
-       *
-       * @return chain address.
        **/
       void set_chain_address(uint32_t value)
          {
diff --git a/src/lib/pubkey/xmss/xmss_index_registry.h b/src/lib/pubkey/xmss/xmss_index_registry.h
index 28701353d..176eae7b7 100644
--- a/src/lib/pubkey/xmss/xmss_index_registry.h
+++ b/src/lib/pubkey/xmss/xmss_index_registry.h
@@ -76,7 +76,7 @@ class XMSS_Index_Registry
        * Retrieves the index position of a key within the registry or
        * max(size_t) if key has not been found.
        *
-       * @param unique id of the XMSS private key (see make_key_id()).
+       * @param id unique id of the XMSS private key (see make_key_id()).
        *
        * @return index position of key or max(size_t) if key not found.
        **/
diff --git a/src/lib/pubkey/xmss/xmss_publickey.h b/src/lib/pubkey/xmss/xmss_publickey.h
index 9186b16a4..39e20b4cf 100644
--- a/src/lib/pubkey/xmss/xmss_publickey.h
+++ b/src/lib/pubkey/xmss/xmss_publickey.h
@@ -104,8 +104,6 @@ class BOTAN_DLL XMSS_PublicKey : public virtual Public_Key
 
       /**
        * Sets the chosen XMSS signature method
-       *
-       * @return XMSS signature method identifier.
        **/
       void set_xmss_oid(XMSS_Parameters::xmss_algorithm_t xmss_oid)
          {
diff --git a/src/lib/pubkey/xmss/xmss_verification_operation.h b/src/lib/pubkey/xmss/xmss_verification_operation.h
index a967fd0ea..e5b11d809 100644
--- a/src/lib/pubkey/xmss/xmss_verification_operation.h
+++ b/src/lib/pubkey/xmss/xmss_verification_operation.h
@@ -47,7 +47,7 @@ namespace Botan {
        *
        * @param msg A message.
        * @param sig The XMSS signature for msg.
-       * @param adrs A XMSS tree address.
+       * @param ards A XMSS tree address.
        * @param seed A seed.
        *
        * @return An n-byte string holding the value of the root of a tree
@@ -65,7 +65,7 @@ namespace Botan {
        *
        * @param sig A XMSS signature.
        * @param msg The message signed with sig.
-       * @paeam pub_key
+       * @param pub_key the public key
        *
        * @return true if signature sig is valid for msg, false otherwise.
        **/
diff --git a/src/tests/test_sm2.cpp b/src/tests/test_sm2.cpp
index 0361ea3a3..c0d272cbd 100644
--- a/src/tests/test_sm2.cpp
+++ b/src/tests/test_sm2.cpp
@@ -28,7 +28,7 @@ class SM2_Signature_KAT_Tests : public PK_Signature_Generation_Test
             "P,A,B,xG,yG,Order,Cofactor,Ident,Msg,x,Nonce,Signature",
             "") {}
 
-      virtual std::string default_padding(const VarMap& vars) const
+      virtual std::string default_padding(const VarMap& vars) const override
          {
          return get_req_str(vars, "Ident");
          }