From 3b4d98017ab4063819a5f6e9c141912693b38c2e Mon Sep 17 00:00:00 2001
From: Seon-Wook Park <seon.wook@swook.net>
Date: Tue, 9 Jun 2015 18:17:30 +0200
Subject: [PATCH] Add more doxygen comments

---
 .../xphoto/grayworld_white_balance.hpp        | 29 +++++++++++++++++--
 .../xphoto/src/grayworld_white_balance.cpp    |  2 --
 2 files changed, 26 insertions(+), 5 deletions(-)

diff --git a/modules/xphoto/include/opencv2/xphoto/grayworld_white_balance.hpp b/modules/xphoto/include/opencv2/xphoto/grayworld_white_balance.hpp
index eb406e6fe..ad63ba61f 100644
--- a/modules/xphoto/include/opencv2/xphoto/grayworld_white_balance.hpp
+++ b/modules/xphoto/include/opencv2/xphoto/grayworld_white_balance.hpp
@@ -55,10 +55,33 @@ namespace cv { namespace xphoto {
 //! @addtogroup xphoto
 //! @{
 
-    /** @brief The function implements a simple grayworld white balance algorithm.
+    /** @brief Implements a simple grayworld white balance algorithm.
+
+    The function autowbGrayworld scales the values of pixels based on a
+    gray-world assumption which states that the average of all channels
+    should result in a gray image.
+
+    This function adds a modification which thresholds pixels based on their
+    saturation value and only uses pixels below the provided threshold in
+    finding average pixel values.
+
+    Saturation is calculated using the following for a 3-channel RGB image per
+    pixel I and is in the range [0, 1]:
+
+    \f[ \texttt{Saturation} [I] = \frac{\textrm{max}(R,G,B) - \textrm{min}(R,G,B)
+    }{\textrm{max}(R,G,B)} \f]
+
+    A threshold of 1 means that all pixels are used to white-balance, while a
+    threshold of 0 means no pixels are used. Lower thresholds are useful in
+    white-balancing saturated images.
+
+    Currently only works on images of type @ref CV_8UC3.
+
+    @param src Input array.
+    @param dst Output array of the same size and type as src.
+    @param thresh Maximum saturation for a pixel to be included in the
+        gray-world assumption.
 
-    @param src
-    @param dst
     @sa balanceWhite
      */
     CV_EXPORTS_W void autowbGrayworld(InputArray src, OutputArray dst,
diff --git a/modules/xphoto/src/grayworld_white_balance.cpp b/modules/xphoto/src/grayworld_white_balance.cpp
index 8391f4400..686702e64 100644
--- a/modules/xphoto/src/grayworld_white_balance.cpp
+++ b/modules/xphoto/src/grayworld_white_balance.cpp
@@ -44,8 +44,6 @@
 
 namespace cv { namespace xphoto {
 
-    /*!
-     */
     void autowbGrayworld(InputArray _src, OutputArray _dst, const float thresh)
     {