Documentation & bugfixes

android/tagin-app/src/ca/idrc/tagin/app/TaginActivity.java

@@ -58,16 +58,28 @@ public boolean onCreateOptionsMenu(Menu menu) {
 		return true;
 	}
 
+	/**
+	 * Initiates an API request for a new URN.
+	 * @param view
+	 */
 	public void onRequestURN(View view) {
 		mURNRequestButton.setText(R.string.requesting_urn);
 		mTaginManager.apiRequest(TaginService.REQUEST_URN);
 	}
 
+	/**
+	 * Initiates an API request for a list of all fingerprints.
+	 * @param view
+	 */
 	public void onListFingerprints(View view) {
 		mListFingerprintsButton.setText(R.string.requesting_fp_list);
 		mTaginManager.apiRequest(TaginService.REQUEST_LIST_FINGERPRINTS);
 	}
 
+	/**
+	 * Initiates an API request for finding nearby neighbours.
+	 * @param view
+	 */
 	public void onFindNeighbours(View view) {
 		if (mNeighboursEditText.getText().length() < 30) {
 			Toast.makeText(this, R.string.invalid_urn, Toast.LENGTH_SHORT).show();
@@ -95,14 +107,22 @@ public void onReceive(Context context, Intent intent) {
 		}
 	};
 
+	/**
+	 * Updates the UI with the result of the fingerprints.list API request.
+	 * @param result
+	 */
 	private void handleFingerprintsResponse(String result) {
 		FingerprintCollection fps = TaginUtils.deserialize(result, FingerprintCollection.class);
 		if (fps != null) {
-			StringBuffer sb = new StringBuffer();
+			StringBuilder sb = new StringBuilder();
 			List<Fingerprint> items = fps.getItems();
 			if (items != null) {
 				for (Fingerprint fp : items) {
-					sb.append("ID:     " + fp.getId() + "\nURN:   " + fp.getUrn() + "\n\n");
+					sb.append("ID:     ");
+					sb.append(fp.getId());
+					sb.append("\nURN:   ");
+					sb.append(fp.getUrn());
+					sb.append("\n\n");
 				}
 			}
 			mListFPTextView.setText(sb.toString());
@@ -112,6 +132,10 @@ private void handleFingerprintsResponse(String result) {
 		mListFingerprintsButton.setText(R.string.fp_list);
 	}
 
+	/**
+	 * Updates the UI with the result of the URN API request.
+	 * @param urn
+	 */
 	private void handleURNResponse(String urn) {
 		if (urn != null) {
 			mURNTextView.setText(urn);
@@ -121,6 +145,10 @@ private void handleURNResponse(String urn) {
 		mURNRequestButton.setText(R.string.request_urn);
 	}
 
+	/**
+	 * Updates the UI with the result of the neighbours API request.
+	 * @param result
+	 */
 	private void handleNeighboursResponse(String result) {
 		if (result != null) {
 			mNeighboursEditText.setText(result);

android/tagin-app/src/ca/idrc/tagin/app/TagsActivity.java

@@ -48,13 +48,21 @@ public boolean onCreateOptionsMenu(Menu menu) {
 		return true;
 	}
 
+	/**
+	 * Initiates a server request for fetching a URN's label.
+	 * @param view
+	 */
 	public void onGetLabel(View view) {
 		mGetLabelButton.setText(R.string.fetching_label);
 		String urn = mURNText1.getText().toString();
 		GetLabelsTask<TagsActivity> task = new GetLabelsTask<TagsActivity>(this, urn);
 		task.execute();
 	}
 
+	/**
+	 * Initiates a server request for assigning a URN's label.
+	 * @param view
+	 */
 	public void onSetLabel(View view) {
 		mSetLabelButton.setText(R.string.saving_tag);
 		String urn = mURNText2.getText().toString();

android/tagin-app/src/ca/idrc/tagin/app/util/LauncherDialog.java

@@ -35,7 +35,7 @@ private class LauncherDialogBuilder extends AlertDialog.Builder {
 
 		public LauncherDialogBuilder(Activity context) {
 			super(context);
-			CharSequence[] items = {"tagin-api", "tagin-tags"};
+			CharSequence[] items = {"tagin! API Explorer", "tagin! Tags Manager"};
 
 			setCancelable(true);
 			setTitle(R.string.select_service);

android/tagin-lib/src/ca/idrc/tagin/lib/TaginManager.java

@@ -21,14 +21,29 @@ public TaginManager(Context context) {
 		mContext = context;
 	}
 
+	/**
+	 * See {@link apiRequest(String, String, String)}
+	 * @param request
+	 */
 	public void apiRequest(String request) {
 		apiRequest(request, null, null);
 	}
 
+	/**
+	 * See {@link apiRequest(String, String, String)}
+	 * @param request
+	 * @param param
+	 */
 	public void apiRequest(String request, String param) {
 		apiRequest(request, param, null);
 	}
 
+	/**
+	 * Initiates an API request with the specified parameters.
+	 * @param request the request name.
+	 * @param param1 the first parameter.
+	 * @param param2 the second parameter.
+	 */
 	public void apiRequest(String request, String param1, String param2) {
 		Intent intent = new Intent(mContext, TaginService.class);
 		intent.putExtra(TaginService.EXTRA_TYPE, request);

android/tagin-lib/src/ca/idrc/tagin/lib/TaginService.java

@@ -92,6 +92,11 @@ public void onReceive(Context context, Intent intent) {
 		}
 	};
 
+	/**
+	 * Asynchronous task that handles API requests on a background thread.
+	 * @author elyas-bhy
+	 *
+	 */
 	private class ApiRequestTask extends AsyncTask<TaginApiCall, Void, String> {
 
 		private TaginApiCall apiCall = null;

android/tagin-lib/src/ca/idrc/tagin/lib/TaginUtils.java

@@ -8,6 +8,12 @@
 
 public class TaginUtils {
 
+	/**
+	 * Deserializes a JSON response and returns it in its original container.
+	 * @param result the JSON response.
+	 * @param clazz the type of the original container.
+	 * @return the deserialized result if the operation is successful, or null.
+	 */
 	public static <T> T deserialize(String result, Class<T> clazz) {
 		T container = null;
 		if (result != null) {

android/tagin-lib/src/ca/idrc/tagin/lib/requests/FindNeighboursRequest.java

@@ -21,6 +21,9 @@ public FindNeighboursRequest(Tagin tagin, String urn, String count) {
 		mMaxCount = Integer.parseInt(count);
 	}
 
+	/**
+	 * {@inheritDoc}
+	 */
 	@Override
 	public String execute() {
 		String result = null;
@@ -33,6 +36,9 @@ public String execute() {
 		return result;
 	}
 
+	/**
+	 * {@inheritDoc}
+	 */
 	@Override
 	public String getBroadcastAction() {
 		return TaginService.ACTION_NEIGHBOURS_READY;

android/tagin-lib/src/ca/idrc/tagin/lib/requests/ListFingerprintsRequest.java

@@ -18,6 +18,9 @@ public ListFingerprintsRequest(Tagin tagin) {
 		mTagin = tagin;
 	}
 
+	/**
+	 * {@inheritDoc}
+	 */
 	@Override
 	public String execute() {	
 		String result = null;
@@ -30,6 +33,9 @@ public String execute() {
 		return result;
 	}
 
+	/**
+	 * {@inheritDoc}
+	 */
 	@Override
 	public String getBroadcastAction() {
 		return TaginService.ACTION_FINGERPRINTS_READY;

android/tagin-lib/src/ca/idrc/tagin/lib/requests/TaginApiCall.java

@@ -2,8 +2,16 @@
 
 public interface TaginApiCall {
 
+	/**
+	 * Executes the API call, and returns the result if successful, or null.
+	 * @return
+	 */
 	public String execute();
 
+	/**
+	 * Returns the broadcast action specific to the API call.
+	 * @return
+	 */
 	public String getBroadcastAction();
 
 }

android/tagin-lib/src/ca/idrc/tagin/lib/requests/URNRequest.java

@@ -20,6 +20,9 @@ public URNRequest(Tagin tagin, Pattern pattern) {
 		mPattern = pattern;
 	}
 
+	/**
+	 * {@inheritDoc}
+	 */
 	@Override
 	public String execute() {
 		String result = null;
@@ -33,6 +36,9 @@ public String execute() {
 		return result;
 	}
 
+	/**
+	 * {@inheritDoc}
+	 */
 	@Override
 	public String getBroadcastAction() {
 		return TaginService.ACTION_URN_READY;

android/tagin-lib/src/ca/idrc/tagin/lib/tags/GetLabelsTask.java

@@ -19,7 +19,12 @@
 import com.google.gson.Gson;
 import com.google.gson.reflect.TypeToken;
 
-
+/**
+ * Asynchronous task responsible for fetching the labels of the specified URN.
+ * @author elyas-bhy
+ *
+ * @param <T>
+ */
 public class GetLabelsTask<T extends Context & GetLabelsTaskListener> extends AsyncTask<Void, Void, List<String>> {
 
 	private T mContext;

android/tagin-lib/src/ca/idrc/tagin/lib/tags/GetLabelsTaskListener.java

@@ -4,6 +4,11 @@
 
 public interface GetLabelsTaskListener {
 
+	/**
+	 * Callback method when GetLabelsTask is executed.
+	 * @param urn the specified URN for which the labels are requested.
+	 * @param labels a list of labels related to the URN.
+	 */
 	public void onGetLabelsTaskComplete(String urn, List<String> labels);
 
 }

android/tagin-lib/src/ca/idrc/tagin/lib/tags/SetLabelTask.java

@@ -15,6 +15,12 @@
 import android.os.AsyncTask;
 import ca.idrc.tagin.lib.TaginManager;
 
+/**
+ * Asynchronous task responsible for assigning a label to the specified URN
+ * @author elyas-bhy
+ *
+ * @param <T>
+ */
 public class SetLabelTask<T extends Context & SetLabelTaskListener> extends AsyncTask<Void, Void, Boolean> {
 
 	private T mContext;

android/tagin-lib/src/ca/idrc/tagin/lib/tags/SetLabelTaskListener.java

@@ -2,6 +2,10 @@
 
 public interface SetLabelTaskListener {
 
+	/**
+	 * Callback method when SetLabelTask is executed.
+	 * @param isSuccessful true if the operation was successful, else false.
+	 */
 	public void onSetLabelTaskComplete(Boolean isSuccessful);
 
 }

experimental/apps/tagin-cloud/AndroidManifest.xml

@@ -4,7 +4,9 @@
     android:versionCode="1"
     android:versionName="1.0" >
 
-    <uses-sdk android:minSdkVersion="14" />
+    <uses-sdk
+        android:minSdkVersion="14"
+        android:targetSdkVersion="14" />
 
     <uses-permission android:name="android.permission.INTERNET" />
     <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
@@ -16,7 +18,8 @@
     <application
         android:name="ca.idrc.tagin.cloud.TaginCloudApp"
         android:icon="@drawable/tagin_cloud_logo"
-        android:label="@string/app_name" >
+        android:label="@string/app_name"
+        android:hardwareAccelerated="true">
         <activity
             android:name="ca.idrc.tagin.cloud.MainActivity"
             android:label="@string/app_name" >

experimental/apps/tagin-cloud/res/values/strings.xml

@@ -12,6 +12,7 @@
     <string name="urn_value">URN value</string>
     <string name="current_labels">Current labels:</string>
     <string name="new_label">New label</string>
+    <string name="missing_data">Missing data. Please fill out all fields before submitting.</string>
 
     <string name="fetching_urn">Fetching URN&#8230;</string>
     <string name="add_new_tag">Add a new tag</string>
@@ -20,6 +21,7 @@
     <string name="cancel">Cancel</string>
 
     <string name="showcase_title">Welcome to tagin-cloud!</string>
-    <string name="shwocase_message">There are no tags available yet for this location! Use the + button on the actionbar to add a new tag.</string>
+    <string name="showcase_message">There are no tags available yet for this location! Use the + button on the actionbar to add a new tag.</string>
+    <string name="to_rotate_sphere">To rotate the sphere, press on the edges of your device\'s screen.</string>
 
 </resources>