more ai generated doc with human review

libs/main/digest/pidigest.h

@@ -1,32 +1,33 @@
-/*! \file pidigest.h
- * \ingroup Core
- * \~\brief
- * \~english Digest algorithms
- * \~russian Алгоритмы хэш-сумм
- *
- * \~\details
- * \~english
- * This file implements several common-usage hash algorithms
- * \~russian
- * Этот файл реализует несколько распространенных алгоритмов хэширования
- */
+//! \addtogroup Core
+//! \{
+//! \file pidigest.h
+//! \brief
+//! \~english Digest algorithms
+//! \~russian Алгоритмы хэш-сумм
+//!
+//! \details
+//! \~english
+//! This file implements several common-usage hash algorithms
+//! \~russian
+//! Этот файл реализует несколько распространенных алгоритмов хэширования
+//! \}
 /*
-	PIP - Platform Independent Primitives
-	Digest algorithms
-	Ivan Pelipenko peri4ko@yandex.ru
+    PIP - Platform Independent Primitives
+    Digest algorithms
+    Ivan Pelipenko peri4ko@yandex.ru
 
-	This program is free software: you can redistribute it and/or modify
-	it under the terms of the GNU Lesser General Public License as published by
-	the Free Software Foundation, either version 3 of the License, or
-	(at your option) any later version.
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Lesser General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
 
-	This program is distributed in the hope that it will be useful,
-	but WITHOUT ANY WARRANTY; without even the implied warranty of
-	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-	GNU Lesser General Public License for more details.
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Lesser General Public License for more details.
 
-	You should have received a copy of the GNU Lesser General Public License
-	along with this program.  If not, see <http://www.gnu.org/licenses/>.
+    You should have received a copy of the GNU Lesser General Public License
+    along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
 
 #ifndef pidigest_h
@@ -37,6 +38,15 @@
 
 class PIP_EXPORT PIDigest {
 public:
+	//! \~english Hash algorithm type
+	//! \~russian Тип алгоритма хэширования
+	//! \details
+	//! \~english
+	//! Supported algorithms: SHA1, SHA2 family (224, 256, 384, 512, 512_224, 512_256),
+	//! MD2, MD4, MD5, BLAKE2s, BLAKE2b, SipHash
+	//! \~russian
+	//! Поддерживаемые алгоритмы: SHA1, семейство SHA2 (224, 256, 384, 512, 512_224, 512_256),
+	//! MD2, MD4, MD5, BLAKE2s, BLAKE2b, SipHash
 	enum class Type {
 		SHA1,
 
@@ -70,13 +80,45 @@ public:
 		Count,
 	};
 
+	//! \~english Get hash output length in bytes
+	//! \~russian Получить длину хэша в байтах
 	static int hashLength(Type type);
+	//! \~english Get hash block length in bytes
+	//! \~russian Получить длину блока хэширования в байтах
 	static int blockLength(Type type);
+	//! \~english Get algorithm name as string
+	//! \~russian Получить название алгоритма в виде строки
+	//! \return Algorithm name
+	//! \sa Type
 	static PIConstChars typeName(Type type);
 
+	//! \~english Calculate hash of message
+	//! \~russian Вычислить хэш сообщения
+	//! \param msg Input message
+	//! \param type Hash algorithm type
+	//! \return Hash bytes
+	//! \sa calculateWithKey, HMAC
 	static PIByteArray calculate(const PIByteArray & msg, Type type);
+	//! \~english Calculate keyed hash of message
+	//! \~russian Вычислить ключевой хэш сообщения
+	//! \param msg Input message
+	//! \param key Secret key
+	//! \param type Hash algorithm type (SipHash or BLAKE2)
+	//! \return Hash bytes
+	//! \note Only SipHash and BLAKE2 algorithms support keyed hashing
+	//! \sa calculate, HMAC
 	static PIByteArray calculateWithKey(const PIByteArray & msg, const PIByteArray & key, Type type);
+	//! \~english Calculate HMAC (Keyed-Hash Message Authentication Code)
+	//! \~russian Вычислить HMAC (код аутентификации сообщений на основе ключа)
+	//! \param msg Input message
+	//! \param key Secret key
+	//! \param type Hash algorithm type
+	//! \return HMAC bytes
+	//! \note Supports SHA1, SHA2 and MD5 algorithms
+	//! \sa calculate, calculateWithKey
 	static PIByteArray HMAC(const PIByteArray & msg, const PIByteArray & key, PIDigest::Type type);
 };
 
+//! \}
+
 #endif