Merge pull request opencv#26260 from sturkmen72:upd_doc_4_x

Update Documentation opencv#26260

### Pull Request Readiness Checklist

See details at https://github.com/opencv/opencv/wiki/How_to_contribute#making-a-good-pull-request

- [x] I agree to contribute to the project under Apache 2 License.
- [x] To the best of my knowledge, the proposed patch is not based on a code under GPL or another license that is incompatible with OpenCV
- [x] The PR is proposed to the proper branch
- [ ] There is a reference to the original bug report and related work
- [ ] There is accuracy test, performance test and test data in opencv_extra repository, if applicable
      Patch to opencv_extra has the same branch name.
- [ ] The feature is well documented and sample code can be built with the project CMake

doc/tutorials/core/file_input_output_with_xml_yml/file_input_output_with_xml_yml.markdown

@@ -1,4 +1,4 @@
-File Input and Output using XML and YAML files {#tutorial_file_input_output_with_xml_yml}
+File Input and Output using XML / YAML / JSON files {#tutorial_file_input_output_with_xml_yml}
 ==============================================
 
 @tableofcontents
@@ -14,12 +14,12 @@ File Input and Output using XML and YAML files {#tutorial_file_input_output_with
 Goal
 ----
 
-You'll find answers for the following questions:
+You'll find answers to the following questions:
 
--   How to print and read text entries to a file and OpenCV using YAML or XML files?
--   How to do the same for OpenCV data structures?
--   How to do this for your data structures?
--   Usage of OpenCV data structures such as @ref cv::FileStorage , @ref cv::FileNode or @ref
+-   How do you print and read text entries to a file in OpenCV using YAML, XML, or JSON files?
+-   How can you perform the same operations for OpenCV data structures?
+-   How can this be done for your custom data structures?
+-   How do you use OpenCV data structures, such as @ref cv::FileStorage , @ref cv::FileNode or @ref
     cv::FileNodeIterator .
 
 Source code
@@ -49,14 +49,14 @@ Here's a sample code of how to achieve all the stuff enumerated at the goal list
 Explanation
 -----------
 
-Here we talk only about XML and YAML file inputs. Your output (and its respective input) file may
+Here we talk only about XML, YAML and JSON file inputs. Your output (and its respective input) file may
 have only one of these extensions and the structure coming from this. They are two kinds of data
 structures you may serialize: *mappings* (like the STL map and the Python dictionary) and *element sequence* (like the STL
 vector). The difference between these is that in a map every element has a unique name through what
 you may access it. For sequences you need to go through them to query a specific item.
 
--#  **XML/YAML File Open and Close.** Before you write any content to such file you need to open it
-    and at the end to close it. The XML/YAML data structure in OpenCV is @ref cv::FileStorage . To
+-#  **XML/YAML/JSON File Open and Close.** Before you write any content to such file you need to open it
+    and at the end to close it. The XML/YAML/JSON data structure in OpenCV is @ref cv::FileStorage . To
     specify that this structure to which file binds on your hard drive you can use either its
     constructor or the *open()* function of this:
     @add_toggle_cpp

modules/core/doc/intro.markdown

@@ -14,15 +14,21 @@ libraries. The following modules are available:
 -   @ref imgproc (**imgproc**) - an image processing module that includes linear and non-linear image filtering,
     geometrical image transformations (resize, affine and perspective warping, generic table-based
     remapping), color space conversion, histograms, and so on.
+-   @ref imgcodecs (**imgcodecs**) - includes functions for reading and writing image files in various formats.
+-   @ref videoio (**videoio**) - an easy-to-use interface to video capturing and video codecs.
+-   @ref highgui (**highgui**) - an easy-to-use interface to simple UI capabilities.
 -   @ref video (**video**) - a video analysis module that includes motion estimation, background subtraction,
     and object tracking algorithms.
 -   @ref calib3d (**calib3d**) - basic multiple-view geometry algorithms, single and stereo camera calibration,
     object pose estimation, stereo correspondence algorithms, and elements of 3D reconstruction.
 -   @ref features2d (**features2d**) - salient feature detectors, descriptors, and descriptor matchers.
 -   @ref objdetect (**objdetect**) - detection of objects and instances of the predefined classes (for example,
     faces, eyes, mugs, people, cars, and so on).
--   @ref highgui (**highgui**) - an easy-to-use interface to simple UI capabilities.
--   @ref videoio (**videoio**) - an easy-to-use interface to video capturing and video codecs.
+-   @ref dnn (**dnn**) - Deep Neural Network module.
+-   @ref ml (**ml**) - The Machine Learning module includes a set of classes and functions for statistical classification,
+    regression, and clustering of data.
+-   @ref photo (**photo**) - advanced photo processing techniques like denoising, inpainting.
+-   @ref stitching (**stitching**) - functions for image stitching and panorama creation.
 -   ... some other helper modules, such as FLANN and Google test wrappers, Python bindings, and
     others.
 

modules/core/include/opencv2/core.hpp

@@ -60,11 +60,16 @@
 
 /**
 @defgroup core Core functionality
+
+The Core module is the backbone of OpenCV, offering fundamental data structures, matrix operations,
+and utility functions that other modules depend on. It’s essential for handling image data,
+performing mathematical computations, and managing memory efficiently within the OpenCV ecosystem.
+
 @{
     @defgroup core_basic Basic structures
     @defgroup core_array Operations on arrays
     @defgroup core_async Asynchronous API
-    @defgroup core_xml XML/YAML Persistence
+    @defgroup core_xml XML/YAML/JSON Persistence
     @defgroup core_cluster Clustering
     @defgroup core_utils Utility and system functions and macros
     @{
@@ -76,7 +81,6 @@
         @defgroup core_utils_samples Utility functions for OpenCV samples
     @}
     @defgroup core_opengl OpenGL interoperability
-    @defgroup core_ipp Intel IPP Asynchronous C/C++ Converters
     @defgroup core_optim Optimization Algorithms
     @defgroup core_directx DirectX interoperability
     @defgroup core_eigen Eigen support
@@ -96,6 +100,7 @@
     @{
         @defgroup core_parallel_backend Parallel backends API
     @}
+    @defgroup core_quaternion Quaternion
 @}
  */
 
@@ -163,7 +168,7 @@ enum SortFlags { SORT_EVERY_ROW    = 0, //!< each matrix row is sorted independe
 
 //! @} core_utils
 
-//! @addtogroup core
+//! @addtogroup core_array
 //! @{
 
 //! Covariation flags
@@ -202,47 +207,19 @@ enum CovarFlags {
     COVAR_COLS      = 16
 };
 
-//! @addtogroup core_cluster
-//!  @{
-
-//! k-Means flags
-enum KmeansFlags {
-    /** Select random initial centers in each attempt.*/
-    KMEANS_RANDOM_CENTERS     = 0,
-    /** Use kmeans++ center initialization by Arthur and Vassilvitskii [Arthur2007].*/
-    KMEANS_PP_CENTERS         = 2,
-    /** During the first (and possibly the only) attempt, use the
-        user-supplied labels instead of computing them from the initial centers. For the second and
-        further attempts, use the random or semi-random centers. Use one of KMEANS_\*_CENTERS flag
-        to specify the exact method.*/
-    KMEANS_USE_INITIAL_LABELS = 1
-};
-
-//! @} core_cluster
-
-//! @addtogroup core_array
-//! @{
-
 enum ReduceTypes { REDUCE_SUM = 0, //!< the output is the sum of all rows/columns of the matrix.
                    REDUCE_AVG = 1, //!< the output is the mean vector of all rows/columns of the matrix.
                    REDUCE_MAX = 2, //!< the output is the maximum (column/row-wise) of all rows/columns of the matrix.
                    REDUCE_MIN = 3,  //!< the output is the minimum (column/row-wise) of all rows/columns of the matrix.
                    REDUCE_SUM2 = 4  //!< the output is the sum of all squared rows/columns of the matrix.
                  };
 
-//! @} core_array
-
 /** @brief Swaps two matrices
 */
 CV_EXPORTS void swap(Mat& a, Mat& b);
 /** @overload */
 CV_EXPORTS void swap( UMat& a, UMat& b );
 
-//! @} core
-
-//! @addtogroup core_array
-//! @{
-
 /** @brief Computes the source location of an extrapolated pixel.
 
 The function computes and returns the coordinate of a donor pixel corresponding to the specified
@@ -557,6 +534,10 @@ The format of half precision floating point is defined in IEEE 754-2008.
 */
 CV_EXPORTS_W void convertFp16(InputArray src, OutputArray dst);
 
+/** @example samples/cpp/tutorial_code/core/how_to_scan_images/how_to_scan_images.cpp
+Check @ref tutorial_how_to_scan_images "the corresponding tutorial" for more details
+*/
+
 /** @brief Performs a look-up table transform of an array.
 
 The function LUT fills the output array with values from the look-up table. Indices of the entries
@@ -3085,8 +3066,21 @@ class CV_EXPORTS RNG_MT19937
 //! @addtogroup core_cluster
 //!  @{
 
+//! k-means flags
+enum KmeansFlags {
+    /** Select random initial centers in each attempt.*/
+    KMEANS_RANDOM_CENTERS     = 0,
+    /** Use kmeans++ center initialization by Arthur and Vassilvitskii [Arthur2007].*/
+    KMEANS_PP_CENTERS         = 2,
+    /** During the first (and possibly the only) attempt, use the
+        user-supplied labels instead of computing them from the initial centers. For the second and
+        further attempts, use the random or semi-random centers. Use one of KMEANS_\*_CENTERS flag
+        to specify the exact method.*/
+    KMEANS_USE_INITIAL_LABELS = 1
+};
+
 /** @example samples/cpp/kmeans.cpp
-An example on K-means clustering
+An example on k-means clustering
 */
 
 /** @brief Finds centers of clusters and groups input samples around the clusters.
@@ -3096,7 +3090,7 @@ and groups the input samples around the clusters. As an output, \f$\texttt{bestL
 0-based cluster index for the sample stored in the \f$i^{th}\f$ row of the samples matrix.
 
 @note
--   (Python) An example on K-means clustering can be found at
+-   (Python) An example on k-means clustering can be found at
     opencv_source_code/samples/python/kmeans.py
 @param data Data for clustering. An array of N-Dimensional points with float coordinates is needed.
 Examples of this array can be:

modules/core/include/opencv2/core/affine.hpp

@@ -51,7 +51,7 @@
 namespace cv
 {
 
-//! @addtogroup core
+//! @addtogroup core_eigen
 //! @{
 
     /** @brief Affine transform

modules/core/include/opencv2/core/base.hpp

@@ -288,28 +288,28 @@ enum BorderTypes {
 By default the function prints information about the error to stderr,
 then it either stops if setBreakOnError() had been called before or raises the exception.
 It is possible to alternate error processing by using redirectError().
-@param _code - error code (Error::Code)
-@param _err - error description
-@param _func - function name. Available only when the compiler supports getting it
-@param _file - source file name where the error has occurred
-@param _line - line number in the source file where the error has occurred
+@param code - error code (Error::Code)
+@param err - error description
+@param func - function name. Available only when the compiler supports getting it
+@param file - source file name where the error has occurred
+@param line - line number in the source file where the error has occurred
 @see CV_Error, CV_Error_, CV_Assert, CV_DbgAssert
  */
-CV_EXPORTS CV_NORETURN void error(int _code, const String& _err, const char* _func, const char* _file, int _line);
+CV_EXPORTS CV_NORETURN void error(int code, const String& err, const char* func, const char* file, int line);
 
 /*! @brief Signals an error and terminate application.
 
 By default the function prints information about the error to stderr, then it terminates application
 with std::terminate. The function is designed for invariants check in functions and methods with
 noexcept attribute.
-@param _code - error code (Error::Code)
-@param _err - error description
-@param _func - function name. Available only when the compiler supports getting it
-@param _file - source file name where the error has occurred
-@param _line - line number in the source file where the error has occurred
+@param code - error code (Error::Code)
+@param err - error description
+@param func - function name. Available only when the compiler supports getting it
+@param file - source file name where the error has occurred
+@param line - line number in the source file where the error has occurred
 @see CV_AssertTerminate
  */
-CV_EXPORTS CV_NORETURN void terminate(int _code, const String& _err, const char* _func, const char* _file, int _line) CV_NOEXCEPT;
+CV_EXPORTS CV_NORETURN void terminate(int code, const String& err, const char* func, const char* file, int line) CV_NOEXCEPT;
 
 
 #ifdef CV_STATIC_ANALYSIS

modules/core/include/opencv2/core/bufferpool.hpp

@@ -15,7 +15,7 @@
 namespace cv
 {
 
-//! @addtogroup core
+//! @addtogroup core_opencl
 //! @{
 
 class BufferPoolController

modules/core/include/opencv2/core/dualquaternion.hpp

@@ -30,7 +30,7 @@
 #include <opencv2/core/affine.hpp>
 
 namespace cv{
-//! @addtogroup core
+//! @addtogroup core_quaternion
 //! @{
 
 template <typename _Tp> class DualQuat;

modules/core/include/opencv2/core/mat.hpp

@@ -446,6 +446,22 @@ typedef OutputArray OutputArrayOfArrays;
 typedef const _InputOutputArray& InputOutputArray;
 typedef InputOutputArray InputOutputArrayOfArrays;
 
+/** @brief Returns an empty InputArray or OutputArray.
+
+ This function is used to provide an "empty" or "null" array when certain functions
+ take optional input or output arrays that you don't want to provide.
+
+ Many OpenCV functions accept optional arguments as `cv::InputArray` or `cv::OutputArray`.
+ When you don't want to pass any data for these optional parameters, you can use `cv::noArray()`
+ to indicate that you are omitting them.
+
+ @return An empty `cv::InputArray` or `cv::OutputArray` that can be used as a placeholder.
+
+ @note This is often used when a function has optional arrays, and you do not want to
+ provide a specific input or output array.
+
+ @see cv::InputArray, cv::OutputArray
+ */
 CV_EXPORTS InputOutputArray noArray();
 
 /////////////////////////////////// MatAllocator //////////////////////////////////////

modules/core/include/opencv2/core/operations.hpp

@@ -508,7 +508,7 @@ The generic function partition implements an \f$O(N^2)\f$ algorithm for splittin
 into one or more equivalency classes, as described in
 <http://en.wikipedia.org/wiki/Disjoint-set_data_structure> . The function returns the number of
 equivalency classes.
-@param _vec Set of elements stored as a vector.
+@param vec Set of elements stored as a vector.
 @param labels Output vector of labels. It contains as many elements as vec. Each label labels[i] is
 a 0-based cluster index of `vec[i]`.
 @param predicate Equivalence predicate (pointer to a boolean function of two arguments or an
@@ -518,11 +518,11 @@ may or may not be in the same class.
 @ingroup core_cluster
 */
 template<typename _Tp, class _EqPredicate> int
-partition( const std::vector<_Tp>& _vec, std::vector<int>& labels,
+partition( const std::vector<_Tp>& vec, std::vector<int>& labels,
           _EqPredicate predicate=_EqPredicate())
 {
-    int i, j, N = (int)_vec.size();
-    const _Tp* vec = &_vec[0];
+    int i, j, N = (int)vec.size();
+    const _Tp* _vec = &vec[0];
 
     const int PARENT=0;
     const int RANK=1;
@@ -548,7 +548,7 @@ partition( const std::vector<_Tp>& _vec, std::vector<int>& labels,
 
         for( j = 0; j < N; j++ )
         {
-            if( i == j || !predicate(vec[i], vec[j]))
+            if( i == j || !predicate(_vec[i], _vec[j]))
                 continue;
             int root2 = j;