COMMON: Add documentation to Common::Encoding

1 files changed, 154 insertions, 1 deletions

diff --git a/common/encoding.h b/common/encoding.h
index bccfb36b0a..b55c485efd 100644
--- a/common/encoding.h
+++ b/common/encoding.h
@@ -37,37 +37,190 @@ typedef void* iconv_t;
 
 namespace Common {
 
+/**
+ * A class, that allows conversion between different text encoding,
+ * the encodings available depend on the current backend and if the
+ * ScummVM is compiled with or without iconv.
+ */
 class Encoding {
 	public:
+		/**
+		 * Constructs everything needed for the conversion between 2 encodings
+		 * and saves the values for future use.
+		 *
+		 * @param to Name of the encoding the strings will be converted to
+		 * @param from Name of the encoding the strings will be converted from
+		 */
 		Encoding(const String &to, const String &from);
 		~Encoding();
 
+		/**
+		 * Converts string between encodings. The resulting string is ended by 
+		 * a character with value 0 (C-like ending for 1 byte per character
+		 * encodings, 2 zero bytes for UTF-16, 4 zero bytes for UTF-32)
+		 *
+		 * The result has to be freed after use.
+		 *
+		 * @param string String that should be converted.
+		 * @param length Length of the string to convert in bytes.
+		 *
+		 * @return Converted string (must be freed) or nullptr if the conversion failed
+		 */
 		char *convert(const char *string, size_t length);
+
+		/**
+		 * Static version of the method above.
+		 * Converts string between encodings. The resulting string is ended by 
+		 * a character with value 0 (C-like ending for 1 byte per character
+		 * encodings, 2 zero bytes for UTF-16, 4 zero bytes for UTF-32)
+		 *
+		 * The result has to be freed after use.
+		 *
+		 * @param to Name of the encoding the strings will be converted to
+		 * @param from Name of the encoding the strings will be converted from
+		 * @param string String that should be converted.
+		 * @param length Length of the string to convert in bytes.
+		 *
+		 * @return Converted string (must be freed) or nullptr if the conversion failed
+		 */
 		static char *convert(const String &to, const String &from, const char *string, size_t length);
 
+		/**
+		 * @return The encoding, which is currently being converted from
+		 */
 		String getFrom() {return _from;};
+
+		/**
+		 * @param from The encoding, to convert from
+		 */
 		void setFrom(const String &from) {_from = from;};
 
+		/**
+		 * @return The encoding, which is currently being converted to
+		 */
 		String getTo() {return _to;};
+
+		/**
+		 * @param to The encoding, to convert to
+		 */
 		void setTo(const String &to) {_to = to;};
 	
 	private:
+		/** The encoding, which is currently being converted to */
 		String _to;
+
+		/** The encoding, which is currently being converted from */
 		String _from;
 
+		/**
+		 * iconvHandle currently used for conversions (is void pointer to 0
+		 * if the ScummVM isn't compiled with iconv)
+		 */
+		iconv_t _iconvHandle;
+
+		/**
+		 * Takes care of transliteration and calls conversion2 for the encoding
+		 * conversion
+		 *
+		 * The result has to be freed after use.
+		 *
+		 * @param iconvHandle Handle to use for the conversion
+		 * @param to Name of the encoding the strings will be converted to
+		 * @param from Name of the encoding the strings will be converted from
+		 * @param string String that should be converted.
+		 * @param length Length of the string to convert in bytes.
+		 *
+		 * @return Converted string (must be freed) or nullptr if the conversion failed
+		 */
 		static char *conversion(iconv_t iconvHandle, const String &to, const String &from, const char *string, size_t length);
 
+		/**
+		 * Calls as many conversion functions as possible or until the conversion
+		 * succeeds. It first tries to use iconv, then it tries to use platform
+		 * specific functions and after that it tries to use TransMan mapping.
+		 *
+		 * The result has to be freed after use.
+		 *
+		 * @param iconvHandle Handle to use for the conversion
+		 * @param to Name of the encoding the strings will be converted to
+		 * @param from Name of the encoding the strings will be converted from
+		 * @param string String that should be converted.
+		 * @param length Length of the string to convert in bytes.
+		 *
+		 * @return Converted string (must be freed) or nullptr if the conversion failed
+		 */
 		static char *conversion2(iconv_t iconvHandle, const String &to, const String &from, const char *string, size_t length);
 
-		iconv_t _iconvHandle;
+		/**
+		 * Tries to convert the string using iconv.
+		 *
+		 * The result has to be freed after use.
+		 *
+		 * @param iconvHandle Handle to use for the conversion
+		 * @param string String that should be converted.
+		 * @param length Length of the string to convert in bytes.
+		 *
+		 * @return Converted string (must be freed) or nullptr if the conversion failed
+		 */
 		static char *convertIconv(iconv_t iconvHandle, const char *string, size_t length);
 
+		/**
+		 * Tries to use the TransMan to convert the string. It can convert only
+		 * between UTF-32 and the current GUI charset. It also tries to convert
+		 * from the current GUI charset to UTF-32 and then it calls convert() again.
+		 *
+		 * The result has to be freed after use.
+		 *
+		 * @param to Name of the encoding the strings will be converted to
+		 * @param from Name of the encoding the strings will be converted from
+		 * @param string String that should be converted.
+		 * @param length Length of the string to convert in bytes.
+		 *
+		 * @return Converted string (must be freed) or nullptr if the conversion failed
+		 */
 		static char *convertTransManMapping(const char *to, const char *from, const char *string, size_t length);
 
+		/**
+		 * Transliterates cyrilic string in iso-8859-5 encoding and returns
+		 * it's ASCII (latin) form.
+		 *
+		 * The result has to be freed after use.
+		 *
+		 * @param string String that should be converted
+		 *
+		 * @return Transliterated string in ASCII (must be freed) or nullptr on fail.
+		 */
 		static char *transliterateCyrilic(const char *string);
+
+		/**
+		 * Transliterates cyrilic in UTF-32 string.
+		 *
+		 * The result has to be freed after use.
+		 *
+		 * @param string String that should be converted
+		 * @param length Length of the string in bytes
+		 *
+		 * @return Transliterated string in UTF-32 (must be freed) or nullptr on fail.
+		 */
 		static uint32 *transliterateUTF32(const uint32 *string, size_t length);
 
+		/**
+		 * Inits the iconv handle
+		 *
+		 * The result has to be freed after use.
+		 *
+		 * @param to Name of the encoding the strings will be converted to
+		 * @param from Name of the encoding the strings will be converted from
+		 *
+		 * @return Opened iconv handle or 0 if ScummVM is compiled without iconv
+		 */
 		static iconv_t initIconv(const String &to, const String &from);
+
+		/**
+		 * Deinits the iconv handle
+		 *
+		 * @param iconvHandle Handle that should be deinited
+		 */
 		static void deinitIconv(iconv_t iconvHandle);
 };