android: add comments

Change-Id: I30f8180dd9cf9c94eedca61926ab706f241142df

android/experimental/LOAndroid3/src/java/org/libreoffice/InvalidationHandler.java

@@ -415,10 +415,16 @@ public class InvalidationHandler implements Document.MessageCallback {
         return mState;
     }
 
+    /**
+     * A key event happend (i.e. user started typing.
+     */
     public void keyEvent() {
         mKeyEvent = true;
     }
 
+    /**
+     * The states the overlay.
+     */
     public enum OverlayState {
         /**
          * State where the overlay is empty

android/experimental/LOAndroid3/src/java/org/libreoffice/LOAbout.java

@@ -12,6 +12,9 @@ import android.widget.TextView;
 
 import java.io.File;
 
+/**
+ * The about dialog.
+ */
 public class LOAbout {
 
     private static final String DEFAULT_DOC_PATH = "/assets/example.odt";

android/experimental/LOAndroid3/src/java/org/libreoffice/LOKitShell.java

@@ -21,7 +21,9 @@ import org.libreoffice.canvas.SelectionHandle;
 import org.mozilla.gecko.gfx.ComposedTileLayer;
 import org.mozilla.gecko.gfx.LayerView;
 
-
+/**
+ * Common static LOKit functions, functions to send events.
+ */
 public class LOKitShell {
     private static final String LOGTAG = LOKitShell.class.getSimpleName();
 

android/experimental/LOAndroid3/src/java/org/libreoffice/LibreOfficeMainActivity.java

@@ -19,7 +19,6 @@ import android.widget.ListView;
 import android.widget.Toast;
 
 import org.libreoffice.overlay.DocumentOverlay;
-
 import org.mozilla.gecko.ZoomConstraints;
 import org.mozilla.gecko.gfx.GeckoLayerClient;
 import org.mozilla.gecko.gfx.LayerView;
@@ -178,8 +177,6 @@ public class LibreOfficeMainActivity extends ActionBarActivity {
 
         // create TextCursorLayer
         mDocumentOverlay = new DocumentOverlay(mAppContext, layerView);
-
-
     }
 
     private boolean copyFileToTemp() {

android/experimental/LOAndroid3/src/java/org/libreoffice/ThumbnailCreator.java

@@ -16,6 +16,9 @@ import android.widget.ImageView;
 
 import java.lang.ref.WeakReference;
 
+/**
+ * Create thumbnails for the parts of the document.
+ */
 public class ThumbnailCreator {
     private static final String LOG_TAG = ThumbnailCreator.class.getSimpleName();
     private static final int THUMBNAIL_SIZE = 256;

android/experimental/LOAndroid3/src/java/org/libreoffice/canvas/CanvasElementImplRequirement.java

@@ -2,6 +2,10 @@ package org.libreoffice.canvas;
 
 import android.graphics.Canvas;
 
+/**
+ * The interface defines a set of method that a typical CanvasElement
+ * implementation should implement.
+ */
 interface CanvasElementImplRequirement {
 
     /**

android/experimental/LOAndroid3/src/java/org/libreoffice/canvas/CommonCanvasElement.java

@@ -9,16 +9,25 @@ public abstract class CommonCanvasElement implements CanvasElement, CanvasElemen
 
     private boolean mVisible = false;
 
+    /**
+     * Is element visible?
+     */
     @Override
     public boolean isVisible() {
         return mVisible;
     }
 
+    /**
+     * Set element visibility.
+     */
     @Override
     public void setVisible(boolean visible) {
         mVisible = visible;
     }
 
+    /**
+     * Trigger drawing the element on the canvas.
+     */
     @Override
     public void draw(Canvas canvas) {
         if (isVisible()) {
@@ -26,6 +35,10 @@ public abstract class CommonCanvasElement implements CanvasElement, CanvasElemen
         }
     }
 
+    /**
+     * Hit test. Return true if the element was hit. Directly return false if
+     * the element is invisible.
+     */
     @Override
     public boolean contains(float x, float y) {
         if (!isVisible()) {

android/experimental/LOAndroid3/src/java/org/libreoffice/canvas/Cursor.java

@@ -5,6 +5,9 @@ import android.graphics.Color;
 import android.graphics.Paint;
 import android.graphics.RectF;
 
+/**
+ * Handles the cursor drawing on the canvas.
+ */
 public class Cursor extends CommonCanvasElement {
     private static final float CURSOR_WIDTH = 2f;
     private final Paint mCursorPaint = new Paint();
@@ -12,26 +15,41 @@ public class Cursor extends CommonCanvasElement {
     public RectF mScaledPosition = new RectF();
     public int mAlpha = 0;
 
+    /**
+     * Construct the cursor and set the default values.
+     */
     public Cursor() {
         mCursorPaint.setColor(Color.BLACK);
         mCursorPaint.setAlpha(0xFF);
     }
 
+    /**
+     * Hit test for cursor, always false.
+     */
     @Override
     public boolean onHitTest(float x, float y) {
         return false;
     }
 
+    /**
+     * Draw the cursor.
+     */
     @Override
     public void onDraw(Canvas canvas) {
         canvas.drawRect(mScaledPosition, mCursorPaint);
     }
 
+    /**
+     * Reposition the cursor on screen.
+     */
     public void reposition(RectF rect) {
         mScaledPosition = rect;
         mScaledPosition.right = mScaledPosition.left + CURSOR_WIDTH;
     }
 
+    /**
+     * Cycle the alpha color of the cursor, makes the
+     */
     public void cycleAlpha() {
         mCursorPaint.setAlpha(mCursorPaint.getAlpha() == 0 ? 0xFF : 0);
     }

android/experimental/LOAndroid3/src/java/org/libreoffice/canvas/GraphicSelection.java

@@ -252,10 +252,16 @@ public class GraphicSelection extends CommonCanvasElement {
         }
     }
 
+    /**
+     * When a single press (no dragging happend) was performed.
+     */
     private void onSinglePress(PointF screenPosition) {
         sendGraphicSelection("LongPress", screenPosition);
     }
 
+    /**
+     * Set the visibility of the graphic selection.
+     */
     @Override
     public void setVisible(boolean visible) {
         super.setVisible(visible);

android/experimental/LOAndroid3/src/java/org/libreoffice/canvas/SelectionHandleMiddle.java

@@ -13,11 +13,11 @@ public class SelectionHandleMiddle extends SelectionHandle {
         super(getBitmapForDrawable(context, R.drawable.handle_middle));
     }
 
-    @Override
     /**
      * Change the position of the handle on the screen. Take into account the
      * handle alignment to the center.
      */
+    @Override
     public void reposition(float x, float y) {
         super.reposition(x, y);
         // align to the center

android/experimental/LOAndroid3/src/java/org/libreoffice/overlay/DocumentOverlayView.java

@@ -329,6 +329,11 @@ public class DocumentOverlayView extends View implements View.OnTouchListener {
         return false;
     }
 
+    /**
+     * Change the handle document position.
+     * @param type - the type of the handle
+     * @param position - the new document position
+     */
     public void positionHandle(SelectionHandle.HandleType type, RectF position) {
         SelectionHandle handle = getHandleForType(type);
         if (RectUtils.fuzzyEquals(handle.mDocumentPosition, position)) {
@@ -341,6 +346,10 @@ public class DocumentOverlayView extends View implements View.OnTouchListener {
         repositionWithViewport(metrics.viewportRectLeft, metrics.viewportRectTop, metrics.zoomFactor);
     }
 
+    /**
+     * Hide the handle.
+     * @param type - type of the handle
+     */
     public void hideHandle(SelectionHandle.HandleType type) {
         SelectionHandle handle = getHandleForType(type);
         if (handle.isVisible()) {
@@ -349,6 +358,10 @@ public class DocumentOverlayView extends View implements View.OnTouchListener {
         }
     }
 
+    /**
+     * Show the handle.
+     * @param type - type of the handle
+     */
     public void showHandle(SelectionHandle.HandleType type) {
         SelectionHandle handle = getHandleForType(type);
         if (!handle.isVisible()) {
@@ -357,6 +370,9 @@ public class DocumentOverlayView extends View implements View.OnTouchListener {
         }
     }
 
+    /**
+     * Returns the handle instance for the input type.
+     */
     private SelectionHandle getHandleForType(SelectionHandle.HandleType type) {
         switch(type) {
             case START: