Browse Source

Adding documentation to GTRANS

Joel Bodenmann 4 years ago
parent
commit
39c13d1645
3 changed files with 60 additions and 7 deletions
  1. 1 1
      demos/modules/gtrans/basic/main.c
  2. 8 2
      src/gtrans/gtrans.c
  3. 51 4
      src/gtrans/gtrans.h

+ 1 - 1
demos/modules/gtrans/basic/main.c

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

+ 8 - 2
src/gtrans/gtrans.c

@@ -25,23 +25,29 @@ void _gtransDeinit(void)
25 25
 
26 26
 const char* gtransString(const char* string)
27 27
 {
28
+	// Find the index of the specified string in the base language table
28 29
 	size_t i = 0;
29 30
 	while (1) {
31
+		// Prevent overflow
30 32
 		if (i >= _languageBase->numEntries-1) {
31
-			return 0;
33
+			return string;
32 34
 		}
33 35
 
36
+		// Check if we found the string
34 37
 		if (strcmp(string, _languageBase->strings[i]) == 0) {
35 38
 			break;
36 39
 		}
37 40
 
41
+		// Otherwise keep going
38 42
 		i++;
39 43
 	}
40 44
 
45
+	// Make sure that the index exists in the current language table
41 46
 	if (i >= _languageCurrent->numEntries-1) {
42
-		return 0;
47
+		return string;
43 48
 	}
44 49
 
50
+	// Return the translated string
45 51
 	return _languageCurrent->strings[i];
46 52
 }
47 53
 

+ 51 - 4
src/gtrans/gtrans.h

@@ -10,7 +10,7 @@
10 10
  *
11 11
  * @addtogroup GTRANS
12 12
  *
13
- * @brief	Module to allow changing the language of an application dynamically during run-time.
13
+ * @brief	Module that allows changing the language of an application dynamically during run-time.
14 14
  *
15 15
  * @{
16 16
  */
@@ -22,18 +22,66 @@
22 22
 
23 23
 #if GFX_USE_GTRANS || defined(__DOXYGEN__)
24 24
 
25
+/**
26
+ * @struct transTable
27
+ * @brief A table containing translated strings.
28
+ */
25 29
 typedef struct transTable {
26
-	unsigned numEntries;
27
-	const char** strings;
30
+	unsigned numEntries;    /**< The number of strings that this table contains */
31
+	const char** strings;	/**< The translated strings */
28 32
 } transTable;
29 33
 
30 34
 #ifdef __cplusplus
31 35
 extern "C" {
32 36
 #endif
33 37
 
38
+/**
39
+ * @brief A wrapper macro to make writing and reading translatable applications easier.
40
+ */
41
+#define gt(str) gtransString(str)
42
+
43
+/**
44
+ * @brief Get the string of the current language specified by the string of the base language.
45
+ *
46
+ * @details This function will return the string of the current language that corresponds to
47
+ *			the specified string in the base language.
48
+ * @details This function uses strcmp() internally to compare strings.
49
+ *
50
+ * @param[in] string The string to translate.
51
+ *
52
+ * @return The corresponding string of the current language or the string passed as a parameter if it doesn't exist.
53
+ */
34 54
 const char* gtransString(const char* string);
55
+
56
+/**
57
+ * @brief Get the string at the specified index position of the current language.
58
+ *
59
+ * @details Getting translation strings is a lot faster using the index as an accessor rather
60
+ *          than the string in the base language.
61
+ *
62
+ * @param[in] index The index of the string in the current language translation table.
63
+ *
64
+ * @return The string at the given index of the current language or 0 if it doesn't exist.
65
+ */
35 66
 const char* gtransIndex(unsigned index);
67
+
68
+/**
69
+ * @brief Set the base language.
70
+ *
71
+ * @details A translatable application needs to have a base language. All translations will
72
+ *          be relative to this base language.
73
+ *
74
+ * @param[in] translation The translation table
75
+ */
36 76
 void gtransSetBaseLanguage(const transTable* const translation);
77
+
78
+/**
79
+ * @brief Set the current language.
80
+ *
81
+ * @details All translations will refer to the current language set by calling this function.
82
+ *
83
+ * @param[in] translation The translation table
84
+ */
37 85
 void gtransSetLanguage(const transTable* const translation);
38 86
 
39 87
 #ifdef __cplusplus
@@ -44,4 +92,3 @@ void gtransSetLanguage(const transTable* const translation);
44 92
 
45 93
 #endif /* _TRANS_H */
46 94
 /** @} */
47
-