Updated Documentation (HoughCircles)

Rewrite the note on HoughCircles documentation to make it more clear

Add note to clarify that the output vector of found circles is sorted by
descending order of centres accumulator values.

Also delete reductant lines on the HoughCircles documentation.

Added comments to hough circles function.

Added comments to icvhoughgradient

Misalignment in line 1183 corrected

modules/imgproc/doc/feature_detection.rst

@@ -280,7 +280,7 @@ The function can be used to initialize a point-based tracker of an object.
 
 HoughCircles
 ------------
-Finds circles in a grayscale image using the Hough transform.
+Finds circles in a grayscale image using a modification of the Hough transform.
 
 .. ocv:function:: void HoughCircles( InputArray image, OutputArray circles, int method, double dp, double minDist, double param1=100, double param2=100, int minRadius=0, int maxRadius=0 )
 
@@ -308,8 +308,6 @@ Finds circles in a grayscale image using the Hough transform.
 
     :param maxRadius: Maximum circle radius.
 
-The function finds circles in a grayscale image using a modification of the Hough transform.
-
 Example: ::
 
     #include <opencv2/imgproc.hpp>
@@ -343,6 +341,8 @@ Example: ::
         return 0;
     }
 
+.. note:: The elements of the output vector of found circles ("circles" in the above example) are sorted in descending order of accumulator values. This way, the centres with the most supporting pixels appear first.
+
 .. note:: Usually the function detects the centers of circles well. However, it may fail to find correct radii. You can assist to the function by specifying the radius range ( ``minRadius`` and ``maxRadius`` ) if you know it. Or, you may ignore the returned radius, use only the center, and find the correct radius using an additional procedure.
 
 .. seealso::

modules/imgproc/src/hough.cpp

-/*M///////////////////////////////////////////////////////////////////////////////////////
+/*M///////////////////////////////////////////////////////////////////////////////////////
 //
 //  IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.
 //
@@ -1024,10 +1024,14 @@ icvHoughCirclesGradient( CvMat* img, float dp, float min_dist,
     CvSeqReader reader;
 
     edges.reset(cvCreateMat( img->rows, img->cols, CV_8UC1 ));
+
+    // Use the Canny Edge Detector to detect all the edges in the image.
     cvCanny( img, edges, MAX(canny_threshold/2,1), canny_threshold, 3 );
 
     dx.reset(cvCreateMat( img->rows, img->cols, CV_16SC1 ));
     dy.reset(cvCreateMat( img->rows, img->cols, CV_16SC1 ));
+
+    /*Use the Sobel Derivative to compute the local gradient of all the non-zero pixels in the edge image.*/
     cvSobel( img, dx, 1, 0, 3 );
     cvSobel( img, dy, 0, 1, 3 );
 
@@ -1038,6 +1042,8 @@ icvHoughCirclesGradient( CvMat* img, float dp, float min_dist,
     cvZero(accum);
 
     storage.reset(cvCreateMemStorage());
+    /* Create sequences for the nonzero pixels in the edge image and the centers of circles
+    which could be detected.*/
     nz = cvCreateSeq( CV_32SC2, sizeof(CvSeq), sizeof(CvPoint), storage );
     centers = cvCreateSeq( CV_32SC1, sizeof(CvSeq), sizeof(int), storage );
 
@@ -1118,7 +1124,8 @@ icvHoughCirclesGradient( CvMat* img, float dp, float min_dist,
 
     sort_buf.resize( MAX(center_count,nz_count) );
     cvCvtSeqToArray( centers, &sort_buf[0] );
-
+    /*Sort candidate centers in descending order of their accumulator values, so that the centers
+    with the most supporting pixels appear first.*/
     std::sort(sort_buf.begin(), sort_buf.begin() + center_count, cv::hough_cmp_gt(adata));
     cvClearSeq( centers );
     cvSeqPushMulti( centers, &sort_buf[0], center_count );
@@ -1173,6 +1180,7 @@ icvHoughCirclesGradient( CvMat* img, float dp, float min_dist,
             continue;
         dist_buf->cols = nz_count1;
         cvPow( dist_buf, dist_buf, 0.5 );
+        // Sort non-zero pixels according to their distance from the center.
         std::sort(sort_buf.begin(), sort_buf.begin() + nz_count1, cv::hough_cmp_gt((int*)ddata));
 
         dist_sum = start_dist = ddata[sort_buf[nz_count1-1]];