Add and fix some comments

src/porting_android.h

@@ -20,7 +20,7 @@ with this program; if not, write to the Free Software Foundation, Inc.,
 #pragma once
 
 #ifndef __ANDROID__
-#error this include has to be included on android port only!
+#error This header has to be included on Android port only!
 #endif
 
 #include <jni.h>
@@ -30,15 +30,20 @@ with this program; if not, write to the Free Software Foundation, Inc.,
 #include <string>
 
 namespace porting {
-// java app
+// Java app
 extern android_app *app_global;
 
-// java <-> c++ interaction interface
+// Java <-> C++ interaction interface
 extern JNIEnv *jnienv;
 
-// do initialization required on android only
+/**
+ * Android-only required initialization
+ */
 void initAndroid();
 
+/**
+ * Android-only cleanup
+ */
 void cleanupAndroid();
 
 /**
@@ -47,21 +52,21 @@ void cleanupAndroid();
 void initializePathsAndroid();
 
 /**
- * show text input dialog in java
- * @param acceptButton text to display on accept button
- * @param hint hint to show
- * @param current initial value to display
- * @param editType type of text field
- * (1 = multiline text input; 2 = single line text input; 3 = password field)
+ * Show a text input dialog in Java
+ * @param acceptButton Text to be displayed on the accept button
+ * @param hint Hint to be shown
+ * @param current Initial value to be displayed
+ * @param editType Type of the text field
+ * (1 = multi-line text input; 2 = single-line text input; 3 = password field)
  */
 void showTextInputDialog(const std::string &acceptButton, const std::string &hint,
 		const std::string &current, int editType);
 
 /**
- * show selection dialog in java
- * @param optionList list of options
- * @param listSize size of the list
- * @param selectedIdx selected index
+ * Show a selection dialog in Java
+ * @param optionList The list of options
+ * @param listSize Size of the list
+ * @param selectedIdx Selected index
  */
 void showComboBoxDialog(const std::string optionList[], s32 listSize, s32 selectedIdx);
 
@@ -74,31 +79,42 @@ void openURIAndroid(const std::string &url);
  */
 void shareFileAndroid(const std::string &path);
 
+/*
+ * Types of Android input dialog:
+ * 1. Text input (single/multi-line text and password field)
+ * 2. Selection input (combo box)
+ */
 enum AndroidDialogType { TEXT_INPUT, SELECTION_INPUT };
 
-/**
- * WORKAROUND for not working callbacks from java -> c++
- * get last type of input dialog
+/*
+ * WORKAROUND for not working callbacks from Java -> C++
+ * Get the type of the last input dialog
  */
 AndroidDialogType getLastInputDialogType();
 
+/*
+ * States of Android input dialog:
+ * 1. The dialog is currently shown.
+ * 2. The dialog has its input sent.
+ * 3. The dialog is canceled/dismissed.
+ */
 enum AndroidDialogState { DIALOG_SHOWN, DIALOG_INPUTTED, DIALOG_CANCELED };
 
-/**
- * WORKAROUND for not working callbacks from java -> c++
- * get state of input dialog
+/*
+ * WORKAROUND for not working callbacks from Java -> C++
+ * Get the state of the input dialog
  */
 AndroidDialogState getInputDialogState();
 
-/**
- * WORKAROUND for not working callbacks from java -> c++
- * get text in current/last input dialog
+/*
+ * WORKAROUND for not working callbacks from Java -> C++
+ * Get the text in the current/last input dialog
  */
 std::string getInputDialogValue();
 
-/**
- * WORKAROUND for not working callbacks from java -> c++
- * get selection in current/last input dialog
+/*
+ * WORKAROUND for not working callbacks from Java -> C++
+ * Get the selection in the current/last input dialog
  */
 int getInputDialogSelection();