Adding documentation to GTRANS

demos/modules/gtrans/basic/main.c

@@ -68,7 +68,7 @@ int main(void)
         gdispFillStringBox(20+300*i, 35*j, 300, 35, gtransIndex(j), font, Black, Silver, justifyLeft);
     }
 
-    gdispFillStringBox(20, 300, 300, 25, gtransString("Welcome"), font, Black, Silver, justifyLeft);
+    gdispFillStringBox(20, 300, 300, 25, gt("Welcome"), font, Black, Silver, justifyLeft);
 
 	while (TRUE) {
 		gfxSleepMilliseconds(500);

src/gtrans/gtrans.c

@@ -25,23 +25,29 @@ void _gtransDeinit(void)
 
 const char* gtransString(const char* string)
 {
+	// Find the index of the specified string in the base language table
 	size_t i = 0;
 	while (1) {
+		// Prevent overflow
 		if (i >= _languageBase->numEntries-1) {
-			return 0;
+			return string;
 		}
 
+		// Check if we found the string
 		if (strcmp(string, _languageBase->strings[i]) == 0) {
 			break;
 		}
 
+		// Otherwise keep going
 		i++;
 	}
 
+	// Make sure that the index exists in the current language table
 	if (i >= _languageCurrent->numEntries-1) {
-		return 0;
+		return string;
 	}
 
+	// Return the translated string
 	return _languageCurrent->strings[i];
 }
 

src/gtrans/gtrans.h

@@ -10,7 +10,7 @@
  *
  * @addtogroup GTRANS
  *
- * @brief	Module to allow changing the language of an application dynamically during run-time.
+ * @brief	Module that allows changing the language of an application dynamically during run-time.
  *
  * @{
  */
@@ -22,18 +22,66 @@
 
 #if GFX_USE_GTRANS || defined(__DOXYGEN__)
 
+/**
+ * @struct transTable
+ * @brief A table containing translated strings.
+ */
 typedef struct transTable {
-	unsigned numEntries;
-	const char** strings;
+	unsigned numEntries;    /**< The number of strings that this table contains */
+	const char** strings;	/**< The translated strings */
 } transTable;
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+/**
+ * @brief A wrapper macro to make writing and reading translatable applications easier.
+ */
+#define gt(str) gtransString(str)
+
+/**
+ * @brief Get the string of the current language specified by the string of the base language.
+ *
+ * @details This function will return the string of the current language that corresponds to
+ *			the specified string in the base language.
+ * @details This function uses strcmp() internally to compare strings.
+ *
+ * @param[in] string The string to translate.
+ *
+ * @return The corresponding string of the current language or the string passed as a parameter if it doesn't exist.
+ */
 const char* gtransString(const char* string);
+
+/**
+ * @brief Get the string at the specified index position of the current language.
+ *
+ * @details Getting translation strings is a lot faster using the index as an accessor rather
+ *          than the string in the base language.
+ *
+ * @param[in] index The index of the string in the current language translation table.
+ *
+ * @return The string at the given index of the current language or 0 if it doesn't exist.
+ */
 const char* gtransIndex(unsigned index);
+
+/**
+ * @brief Set the base language.
+ *
+ * @details A translatable application needs to have a base language. All translations will
+ *          be relative to this base language.
+ *
+ * @param[in] translation The translation table
+ */
 void gtransSetBaseLanguage(const transTable* const translation);
+
+/**
+ * @brief Set the current language.
+ *
+ * @details All translations will refer to the current language set by calling this function.
+ *
+ * @param[in] translation The translation table
+ */
 void gtransSetLanguage(const transTable* const translation);
 
 #ifdef __cplusplus
@@ -44,4 +92,3 @@ void gtransSetLanguage(const transTable* const translation);
 
 #endif /* _TRANS_H */
 /** @} */
-