Improved javadoc comments. Draft.

modules/java/generator/src/java/android+AsyncServiceHelper.java

@@ -105,7 +105,7 @@ class AsyncServiceHelper
     }
     
     /**
-     * URI for OpenCV Manager on Google Play (Android Market)
+     *  URL of OpenCV Manager page on Google Play Market.
      */
     protected static final String OPEN_CV_SERVICE_URL = "market://details?id=org.opencv.engine";
 
@@ -263,7 +263,7 @@ class AsyncServiceHelper
             }
             else
             {
-                // If dependencies list is not defined or empty
+                // If dependencies list is not defined or empty.
                 String AbsLibraryPath = Path + File.separator + "libopencv_java.so";
                 result &= loadLibrary(AbsLibraryPath);
             }

modules/java/generator/src/java/android+BaseLoaderCallback.java

@@ -7,7 +7,7 @@ import android.content.DialogInterface.OnClickListener;
 import android.util.Log;
 
 /**
- * Basic implementation of LoaderCallbackInterface
+ * Basic implementation of LoaderCallbackInterface.
  */
 public abstract class BaseLoaderCallback implements LoaderCallbackInterface {
 
@@ -22,9 +22,9 @@ public abstract class BaseLoaderCallback implements LoaderCallbackInterface {
             /** OpenCV initialization was successful. **/
             case LoaderCallbackInterface.SUCCESS:
             {
-                /** Application must override this method to handle successful library initialization **/
+                /** Application must override this method to handle successful library initialization. **/
             } break;
-            /** OpenCV Manager or library package installation is in progress. Restart of application is required **/
+            /** OpenCV Manager or library package installation is in progress. Restart the application. **/
             case LoaderCallbackInterface.RESTART_REQUIRED:
             {
                 Log.d(TAG, "OpenCV downloading. App restart is needed!");
@@ -40,7 +40,7 @@ public abstract class BaseLoaderCallback implements LoaderCallbackInterface {
 
                 RestartMessage.show();
             } break;
-            /** OpenCV loader cannot start Google Play **/
+            /** OpenCV loader cannot start Google Play Market. **/
             case LoaderCallbackInterface.MARKET_ERROR:
             {
                 Log.d(TAG, "Google Play service is not installed! You can get it here");
@@ -55,13 +55,13 @@ public abstract class BaseLoaderCallback implements LoaderCallbackInterface {
                 });
                 MarketErrorMessage.show();
             } break;
-            /** Package installation was canceled **/
+            /** Package installation has been canceled. **/
             case LoaderCallbackInterface.INSTALL_CANCELED:
             {
                 Log.d(TAG, "OpenCV library instalation was canceled by user");
                 mAppContext.finish();
             } break;
-            /** Application is incompatible with this version of OpenCV Manager. Possible Service update is needed **/
+            /** Application is incompatible with this version of OpenCV Manager. Possibly, a service update is required. **/
             case LoaderCallbackInterface.INCOMPATIBLE_MANAGER_VERSION:
             {
                 Log.d(TAG, "OpenCV Manager Service is uncompatible with this app!");
@@ -76,7 +76,7 @@ public abstract class BaseLoaderCallback implements LoaderCallbackInterface {
                 });
                 IncomatibilityMessage.show();
             }
-            /** Other status, i.e. INIT_FAILED **/
+            /** Other status, i.e. INIT_FAILED. **/
             default:
             {
                 Log.e(TAG, "OpenCV loading failed!");

modules/java/generator/src/java/android+InstallCallbackInterface.java

 package org.opencv.android;
 
 /**
- * Installation callback interface
+ * Installation callback interface.
  */
 public interface InstallCallbackInterface
 {
     /**
-     * Target package name
-     * @return Return target package name
+     * Target package name.
+     * @return Return target package name.
      */
     public String getPackageName();
     /**
-     * Installation of package is approved
+     * Installation is approved.
      */
     public void install();
     /**
-     * Installation canceled
+     * Installation is canceled.
      */
     public void cancel();
 };

modules/java/generator/src/java/android+LoaderCallbackInterface.java

 package org.opencv.android;
 
 /**
- * Interface for callback object in case of asynchronous initialization of OpenCV
+ * Interface for callback object in case of asynchronous initialization of OpenCV.
  */
 public interface LoaderCallbackInterface
 {
     /**
-     * OpenCV initialization finished successfully
+     * OpenCV initialization finished successfully.
      */
     static final int SUCCESS = 0;
     /**
-     * OpenCV library installation via Google Play service was initialized. Application restart is required
+     * OpenCV library installation via Google Play service has been initialized. Restart the application.
      */
     static final int RESTART_REQUIRED = 1;
     /**
-     * Google Play (Android Market) cannot be invoked
+     * Google Play Market cannot be invoked.
      */
     static final int MARKET_ERROR = 2;
     /**
-     * OpenCV library installation was canceled by user
+     * OpenCV library installation has been canceled by user.
      */
     static final int INSTALL_CANCELED = 3;
     /**
-     * Version of OpenCV Manager Service is incompatible with this app. Service update is needed
+     * This version of OpenCV Manager Service is incompatible with the app. Possibly, a service update is required.
      */
     static final int INCOMPATIBLE_MANAGER_VERSION = 4;
     /**
-     * OpenCV library initialization failed
+     * OpenCV library initialization failed.
      */
     static final int INIT_FAILED = 0xff;
 
     /**
-     * Callback method that is called after OpenCV library initialization
-     * @param status Status of initialization. See Initialization status constants
+     * This callback method is called after OpenCV library initialization.
+     * @param status Status of initialization (see Initialization status constants).
      */
     public void onManagerConnected(int status);
 
     /**
-     * Callback method that is called in case when package installation is needed
-     * @param callback Answer object with approve and cancel methods and package description
+     * This callback method is called in case the package installation is needed.
+     * @param callback Answer object with approve and cancel methods and the package description.
      */
     public void onPackageInstall(InstallCallbackInterface callback);
 };

modules/java/generator/src/java/android+OpenCVLoader.java

@@ -3,18 +3,18 @@ package org.opencv.android;
 import android.content.Context;
 
 /**
- * Helper class provides common initialization methods for OpenCV library
+ * Helper class provides common initialization methods for OpenCV library.
  */
 public class OpenCVLoader
 {
     /**
-     * OpenCV Library version 2.4.2
+     * OpenCV Library version 2.4.2.
      */
     public static final String OPENCV_VERSION_2_4_2 = "2.4.2";
 
     /**
-     * Load and initialize OpenCV library from current application package. Roughly it is analog of system.loadLibrary("opencv_java")
-     * @return Return true is initialization of OpenCV was successful
+     * Loads and initializes OpenCV library from current application package. Roughly, it's an analog of system.loadLibrary("opencv_java").
+     * @return Returns true is initialization of OpenCV was successful.
      */
     public static boolean initDebug()
     {
@@ -22,11 +22,11 @@ public class OpenCVLoader
     }
 
     /**
-     *  Load and initialize OpenCV library using OpenCV Engine service.
-     * @param Version OpenCV Library version
-     * @param AppContext Application context for connecting to service
-     * @param Callback Object, that implements LoaderCallbackInterface for handling Connection status
-     * @return Return true if initialization of OpenCV starts successfully
+     * Loads and initializes OpenCV library using OpenCV Engine service.
+     * @param Version OpenCV Library version.
+     * @param AppContext Application context for connecting to service.
+     * @param Callback Object, that implements LoaderCallbackInterface for handling Connection status.
+     * @return Returns true if initialization of OpenCV is successful.
      */
     public static boolean initAsync(String Version, Context AppContext,
             LoaderCallbackInterface Callback)

modules/java/generator/src/java/android+StaticHelper.java

@@ -76,7 +76,7 @@ class StaticHelper {
         }
         else
         {
-            // If dependencies list is not defined or empty
+            // If dependencies list is not defined or empty.
             result &= loadLibrary("opencv_java");
         }
 

modules/java/generator/src/java/android+Utils.java

@@ -76,14 +76,14 @@ public class Utils {
     /**
      * Converts Android Bitmap to OpenCV Mat.
      * <p>
-     * The function converts an image in the Android Bitmap representation to the OpenCV Mat.
+     * This function converts an Android Bitmap image to the OpenCV Mat.
      * <br>The 'ARGB_8888' and 'RGB_565' input Bitmap formats are supported.
      * <br>The output Mat is always created of the same size as the input Bitmap and of the 'CV_8UC4' type,
      * it keeps the image in RGBA format.
-     * <br>The function throws an exception if the conversion fails.
+     * <br>This function throws an exception if the conversion fails.
      * @param bmp is a valid input Bitmap object of the type 'ARGB_8888' or 'RGB_565'.
-     * @param mat is a valid output Mat object, it will be reallocated if needed, so it's possible to pass an empty Mat.
-     * @param unPremultiplyAlpha is a flag if the bitmap needs to be converted from alpha premultiplied format (like Android keeps 'ARGB_8888' ones) to regular one. The flag is ignored for 'RGB_565' bitmaps.
+     * @param mat is a valid output Mat object, it will be reallocated if needed, so it may be empty.
+     * @param unPremultiplyAlpha is a flag if the bitmap needs to be converted from alpha premultiplied format (like Android keeps 'ARGB_8888' ones) to regular one. This flag is ignored for 'RGB_565' bitmaps.
      */
     public static void bitmapToMat(Bitmap bmp, Mat mat, boolean unPremultiplyAlpha) {
         if (bmp == null)
@@ -94,7 +94,7 @@ public class Utils {
     }
 
     /**
-     * Shortened form of the bitmapToMat(bmp, mat, unPremultiplyAlpha=false)
+     * Short form of the bitmapToMat(bmp, mat, unPremultiplyAlpha=false).
      * @param bmp is a valid input Bitmap object of the type 'ARGB_8888' or 'RGB_565'.
      * @param mat is a valid output Mat object, it will be reallocated if needed, so it's possible to pass an empty Mat.
      */
@@ -124,7 +124,7 @@ public class Utils {
     }
 
     /**
-     * Shortened form of the <b>matToBitmap(mat, bmp, premultiplyAlpha=false)</b>
+     * Short form of the <b>matToBitmap(mat, bmp, premultiplyAlpha=false)</b>
      * @param mat is a valid input Mat object of the types 'CV_8UC1', 'CV_8UC3' or 'CV_8UC4'.
      * @param bmp is a valid Bitmap object of the same size as the Mat m and of type 'ARGB_8888' or 'RGB_565'.
      */

modules/java/generator/src/java/core+TermCriteria.java

@@ -4,15 +4,15 @@ package org.opencv.core;
 public class TermCriteria {
 
     /**
-     * the maximum number of iterations or elements to compute
+     * the maximum of iterations or elements to compute
      */
     public static final int COUNT = 1;
     /**
-     * the maximum number of iterations or elements to compute
+     * the maximum of iterations or elements to compute
      */
     public static final int MAX_ITER = COUNT;
     /**
-     * the desired accuracy or change in parameters at which the iterative algorithm stops
+     * the desired accuracy threshold or change in parameters at which the iterative algorithm stops.
      */
     public static final int EPS = 2;
 
@@ -21,7 +21,7 @@ public class TermCriteria {
     public double epsilon;
 
     /**
-     * Termination criteria in iterative algorithms
+     * Termination criteria for iterative algorithms.
      * 
      * @param type
      *            the type of termination criteria: COUNT, EPS or COUNT + EPS
@@ -37,7 +37,7 @@ public class TermCriteria {
     }
 
     /**
-     * Termination criteria in iterative algorithms
+     * Termination criteria for iterative algorithms
      */
     public TermCriteria() {
         this(0, 0, 0.0);

modules/java/generator/src/java/engine+OpenCVEngineInterface.aidl

 package org.opencv.engine;
 
 /**
-* Class provides Java interface to OpenCV Engine Service. Is synchronous with native OpenCVEngine class.
+* Class provides a Java interface for OpenCV Engine Service. It's synchronous with native OpenCVEngine class.
 */
 interface OpenCVEngineInterface
 {
 	/**
-	* @return Return service version
+	* @return Returns service version.
 	*/
 	int getEngineVersion();
 
 	/**
-	* Find installed OpenCV library
-	* @param OpenCV version
-	* @return Return path to OpenCV native libs or empty string if OpenCV was not found
+	* Finds an installed OpenCV library.
+	* @param OpenCV version.
+	* @return Returns path to OpenCV native libs or an empty string if OpenCV can not be found.
 	*/
 	String getLibPathByVersion(String version);
 
 	/**
-	* Try to install defined version of OpenCV from Google Play (Android Market).
-	* @param OpenCV version
-	* @return Return true if installation was successful or OpenCV package has been already installed
+	* Tries to install defined version of OpenCV from Google Play Market.
+	* @param OpenCV version.
+	* @return Returns true if installation was successful or OpenCV package has been already installed.
 	*/
 	boolean installVersion(String version);
  
 	/**
-	* Return list of libraries in loading order separated by ";" symbol
-	* @param OpenCV version
-	* @return Return OpenCV libraries names separated by symbol ";" in loading order
+	* Returns list of libraries in loading order, separated by semicolon.
+	* @param OpenCV version.
+	* @return Returns names of OpenCV libraries, separated by semicolon.
 	*/
 	String getLibraryList(String version);
 }
\ No newline at end of file

modules/java/generator/src/java/features2d+DMatch.java

@@ -3,21 +3,21 @@ package org.opencv.features2d;
 //C++: class DMatch
 
 /**
- * Struct for matching: query descriptor index, train descriptor index, train
+ * Structure for matching: query descriptor index, train descriptor index, train
  * image index and distance between descriptors.
  */
 public class DMatch {
 
     /**
-     * query descriptor index
+     * Query descriptor index.
      */
     public int queryIdx;
     /**
-     * train descriptor index
+     * Train descriptor index.
      */
     public int trainIdx;
     /**
-     * train image index
+     * Train image index.
      */
     public int imgIdx;
 
@@ -46,7 +46,7 @@ public class DMatch {
     }
 
     /**
-     * less is better
+     * Less is better.
      */
     public boolean lessThan(DMatch it) {
         return distance < it.distance;

modules/java/generator/src/java/features2d+KeyPoint.java

@@ -6,29 +6,29 @@ import org.opencv.core.Point;
 public class KeyPoint {
 
     /**
-     * coordinates of the keypoint
+     * Coordinates of the keypoint.
      */
     public Point pt;
     /**
-     * diameter of the meaningful keypoint neighborhood
+     * Diameter of the useful keypoint adjacent area.
      */
     public float size;
     /**
-     * computed orientation of the keypoint (-1 if not applicable)
+     * Computed orientation of the keypoint (-1 if not applicable).
      */
     public float angle;
     /**
-     * the response by which the most strong keypoints have been selected. Can
-     * be used for further sorting or subsampling
+     * The response, by which the strongest keypoints have been selected. Can
+     * be used for further sorting or subsampling.
      */
     public float response;
     /**
-     * octave (pyramid layer) from which the keypoint has been extracted
+     * Octave (pyramid layer), from which the keypoint has been extracted.
      */
     public int octave;
     /**
-     * object id that can be used to clustered keypoints by an object they
-     * belong to
+     * Object ID, that can be used to cluster keypoints by an object they
+     * belong to.
      */
     public int class_id;
 

modules/java/generator/src/java/highgui+VideoCapture.java

@@ -47,14 +47,14 @@ public class VideoCapture {
     //
 
 /**
- * Returns the specified "VideoCapture" property
+ * Returns the specified "VideoCapture" property.
  *
  * Note: When querying a property that is not supported by the backend used by
  * the "VideoCapture" class, value 0 is returned.
  *
- * @param propId Property identifier. It can be one of the following:
- *   * CV_CAP_PROP_FRAME_WIDTH Width of the frames in the video stream.
- *   * CV_CAP_PROP_FRAME_HEIGHT Height of the frames in the video stream.
+ * @param propId Property identifier; it can be one of the following:
+ *   * CV_CAP_PROP_FRAME_WIDTH width of the frames in the video stream.
+ *   * CV_CAP_PROP_FRAME_HEIGHT height of the frames in the video stream.
  *
  * @see <a href="http://opencv.itseez.com/modules/highgui/doc/reading_and_writing_images_and_video.html#videocapture-get">org.opencv.highgui.VideoCapture.get</a>
  */
@@ -173,10 +173,10 @@ public class VideoCapture {
 /**
  * Sets a property in the "VideoCapture".
  *
- * @param propId Property identifier. It can be one of the following:
- *   * CV_CAP_PROP_FRAME_WIDTH Width of the frames in the video stream.
- *   * CV_CAP_PROP_FRAME_HEIGHT Height of the frames in the video stream.
- * @param value Value of the property.
+ * @param propId Property identifier; it can be one of the following:
+ *   * CV_CAP_PROP_FRAME_WIDTH width of the frames in the video stream.
+ *   * CV_CAP_PROP_FRAME_HEIGHT height of the frames in the video stream.
+ * @param value value of the property.
  *
  * @see <a href="http://opencv.itseez.com/modules/highgui/doc/reading_and_writing_images_and_video.html#videocapture-set">org.opencv.highgui.VideoCapture.set</a>
  */