Improve the documentation.

modules/core/include/opencv2/core/utility.hpp

@@ -198,12 +198,12 @@ If threads == 0, OpenCV will disable threading optimizations and run all it's fu
 sequentially. Passing threads \< 0 will reset threads number to system default. This function must
 be called outside of parallel region.
 
-OpenCV will try to run it's functions with specified threads number, but some behaviour differs from
+OpenCV will try to run its functions with specified threads number, but some behaviour differs from
 framework:
 -   `TBB` - User-defined parallel constructions will run with the same threads number, if
-    another does not specified. If later on user creates own scheduler, OpenCV will use it.
+    another is not specified. If later on user creates his own scheduler, OpenCV will use it.
 -   `OpenMP` - No special defined behaviour.
--   `Concurrency` - If threads == 1, OpenCV will disable threading optimizations and run it's
+-   `Concurrency` - If threads == 1, OpenCV will disable threading optimizations and run its
     functions sequentially.
 -   `GCD` - Supports only values \<= 0.
 -   `C=` - No special defined behaviour.
@@ -233,7 +233,7 @@ CV_EXPORTS_W int getNumThreads();
 /** @brief Returns the index of the currently executed thread within the current parallel region. Always
 returns 0 if called outside of parallel region.
 
-The exact meaning of return value depends on the threading framework used by OpenCV library:
+The exact meaning of the return value depends on the threading framework used by OpenCV library:
 - `TBB` - Unsupported with current 4.1 TBB release. Maybe will be supported in future.
 - `OpenMP` - The thread number, within the current team, of the calling thread.
 - `Concurrency` - An ID for the virtual processor that the current context is executing on (0
@@ -285,6 +285,19 @@ tm.start();
 tm.stop();
 std::cout << tm.getTimeSec();
 @endcode
+
+It is also possible to compute the average time over multiple runs:
+@code
+TickMeter tm;
+for (int i = 0; i < 100; i++)
+{
+    tm.start();
+    // do something ...
+    tm.stop();
+}
+double average_time = tm.getTimeSec() / tm.getCounter();
+std::cout << "Average time in second per iteration is: " << average_time << std::endl;
+@endcode
 @sa getTickCount, getTickFrequency
 */
 
@@ -428,12 +441,13 @@ The function returns the aligned pointer of the same type as the input pointer:
  */
 template<typename _Tp> static inline _Tp* alignPtr(_Tp* ptr, int n=(int)sizeof(_Tp))
 {
+    CV_DbgAssert((n & (n - 1)) == 0); // n is a power of 2
     return (_Tp*)(((size_t)ptr + n-1) & -n);
 }
 
 /** @brief Aligns a buffer size to the specified number of bytes.
 
-The function returns the minimum number that is greater or equal to sz and is divisible by n :
+The function returns the minimum number that is greater than or equal to sz and is divisible by n :
 \f[\texttt{(sz + n-1) & -n}\f]
 @param sz Buffer size to align.
 @param n Alignment size that must be a power of two.
@@ -482,7 +496,7 @@ The function returns true if the optimized code is enabled. Otherwise, it return
  */
 CV_EXPORTS_W bool useOptimized();
 
-static inline size_t getElemSize(int type) { return CV_ELEM_SIZE(type); }
+static inline size_t getElemSize(int type) { return (size_t)CV_ELEM_SIZE(type); }
 
 /////////////////////////////// Parallel Primitives //////////////////////////////////
 
@@ -526,10 +540,10 @@ template<typename _Tp, typename Functor> inline
 void Mat::forEach_impl(const Functor& operation) {
     if (false) {
         operation(*reinterpret_cast<_Tp*>(0), reinterpret_cast<int*>(0));
-        // If your compiler fail in this line.
+        // If your compiler fails in this line.
         // Please check that your functor signature is
-        //     (_Tp&, const int*)   <- multidimential
-        //  or (_Tp&, void*)        <- in case of you don't need current idx.
+        //     (_Tp&, const int*)   <- multi-dimensional
+        //  or (_Tp&, void*)        <- in case you don't need current idx.
     }
 
     CV_Assert(this->total() / this->size[this->dims - 1] <= INT_MAX);