Merge pull request #16050 from dmatveev:dm/ocv42_gapi_doc_fixup

* G-API: Addressed various documentation issues

- Fixed various typos and missing references;
- Added brief documentaion on G_TYPED_KERNEL and G_COMPOUND_KERNEL macros;
- Briefly described GComputationT<>;
- Briefly described G-API data objects (in a group section).

* G-API: Some clean-ups in doxygen, also a chapter on Render API

* G-API: Expose more graph compilation arguments in the documentation

* G-API: Address documentation review comments

modules/gapi/include/opencv2/gapi.hpp

@@ -13,11 +13,11 @@
 /** \defgroup gapi G-API framework
 @{
     @defgroup gapi_main_classes G-API Main Classes
-    @defgroup gapi_data_objects G-API Data Objects
+    @defgroup gapi_data_objects G-API Data Types
     @{
       @defgroup gapi_meta_args G-API Metadata Descriptors
     @}
-    @defgroup gapi_std_backends G-API Standard backends
+    @defgroup gapi_std_backends G-API Standard Backends
     @defgroup gapi_compile_args G-API Graph Compilation Arguments
 @}
  */

modules/gapi/include/opencv2/gapi/core.hpp

@@ -18,12 +18,12 @@
 #include <opencv2/gapi/gscalar.hpp>
 #include <opencv2/gapi/gkernel.hpp>
 
-/** \defgroup gapi_core G-API core (basic) functionality
+/** \defgroup gapi_core G-API Core functionality
 @{
     @defgroup gapi_math Graph API: Math operations
     @defgroup gapi_pixelwise Graph API: Pixelwise operations
     @defgroup gapi_matrixop Graph API: Operations on matrices
-    @defgroup gapi_transform Graph API: Geometric, depth and LUT-like image transformations
+    @defgroup gapi_transform Graph API: Image and channel composition functions
 @}
  */
 namespace cv { namespace gapi {

modules/gapi/include/opencv2/gapi/fluid/gfluidkernel.hpp

@@ -29,7 +29,7 @@ namespace gapi
 namespace fluid
 {
     /**
-     * \addtogroup gapi_std_backends G-API Standard backends
+     * \addtogroup gapi_std_backends G-API Standard Backends
      * @{
      */
     /**
@@ -97,16 +97,46 @@ public:
 // FIXME!!!
 // This is the temporary and experimental API
 // which should be replaced by runtime roi-based scheduling
+/** \addtogroup gapi_compile_args
+ * @{
+ */
+/**
+ * @brief This structure allows to control the output image region
+ * which Fluid backend will produce in the graph.
+ *
+ * This feature is useful for external tiling and parallelism, but
+ * will be deprecated in the future releases.
+ */
 struct GFluidOutputRois
 {
     std::vector<cv::gapi::own::Rect> rois;
 };
 
+/**
+ * @brief This structure forces Fluid backend to generate multiple
+ * parallel output regions in the graph. These regions execute in parallel.
+ *
+ * This feature may be deprecated in the future releases.
+ */
 struct GFluidParallelOutputRois
 {
     std::vector<GFluidOutputRois> parallel_rois;
 };
 
+/**
+ * @brief This structure allows to customize the way how Fluid executes
+ * parallel regions.
+ *
+ * For example, user can utilize his own threading runtime via this parameter.
+ * The `parallel_for` member functor is called by the Fluid runtime with the
+ * following arguments:
+ *
+ * @param size Size of the parallel range to process
+ * @param f A function which should be called for every integer index
+ *   in this range by the specified parallel_for implementation.
+ *
+ * This feature may be deprecated in the future releases.
+ */
 struct GFluidParallelFor
 {
     //this function accepts:
@@ -114,6 +144,7 @@ struct GFluidParallelFor
     // - and a function to be called on the range items, designated by item index
     std::function<void(std::size_t size, std::function<void(std::size_t index)>)> parallel_for;
 };
+/** @} gapi_compile_args */
 
 namespace detail
 {

modules/gapi/include/opencv2/gapi/gcommon.hpp

@@ -25,10 +25,6 @@ namespace detail
     // This is a trait-like structure to mark backend-specific compile arguments
     // with tags
     template<typename T> struct CompileArgTag;
-    template<typename T> struct CompileArgTag
-    {
-        static const char* tag() { return ""; };
-    };
 
     // These structures are tags which separate kernels and transformations
     struct KernelTag
@@ -62,8 +58,8 @@ namespace detail {
 /** \addtogroup gapi_compile_args
  * @{
  *
- * @brief Compilation arguments: a set of data structures which can be
- * passed to control compilation process
+ * @brief Compilation arguments: data structures controlling the
+ * compilation process
  *
  * G-API comes with a number of graph compilation options which can be
  * passed to cv::GComputation::apply() or

modules/gapi/include/opencv2/gapi/gcompoundkernel.hpp

@@ -101,7 +101,18 @@ public:
 };
 
 } // namespace detail
-#define GAPI_COMPOUND_KERNEL(Name, API) struct Name: public cv::detail::GCompoundKernelImpl<Name, API>
+
+
+/**
+ * Declares a new compound kernel. See this
+ * [documentation chapter](@ref gapi_kernel_compound)
+ * on compound kernels for more details.
+ *
+ * @param Name type name for new kernel
+ * @param API the interface this kernel implements
+ */
+#define GAPI_COMPOUND_KERNEL(Name, API) \
+    struct Name: public cv::detail::GCompoundKernelImpl<Name, API>
 
 } // namespace cv
 

modules/gapi/include/opencv2/gapi/gcomputation.hpp

@@ -39,6 +39,8 @@ namespace detail
 /**
  * \addtogroup gapi_main_classes
  * @{
+ *
+ * @brief G-API classes for constructed and compiled graphs.
  */
 /**
  * @brief GComputation class represents a captured computation

modules/gapi/include/opencv2/gapi/gkernel.hpp

@@ -239,12 +239,31 @@ public:
         static constexpr const char * id() {return Id;}                     \
     };                                                                      \
 //! @endcond
+
+/**
+ * Declares a new G-API Operation. See [Kernel API](@ref gapi_kernel_api)
+ * for more details.
+ *
+ * @param Class type name for this operation.
+ * @param API an `std::function<>`-like signature for the operation;
+ *    return type is a single value.
+ * @param Id string identifier for the operation. Must be unique.
+ */
 #define G_TYPED_KERNEL(Class, API, Id)                                      \
     G_ID_HELPER_BODY(Class, Id)                                             \
     struct Class final: public cv::GKernelType<Class, std::function API >,  \
                         public G_ID_HELPER_CLASS(Class)
 // {body} is to be defined by user
 
+/**
+ * Declares a new G-API Operation. See [Kernel API](@ref gapi_kernel_api)
+ * for more details.
+ *
+ * @param Class type name for this operation.
+ * @param API an `std::function<>`-like signature for the operation;
+ *    return type is a tuple of multiple values.
+ * @param Id string identifier for the operation. Must be unique.
+ */
 #define G_TYPED_KERNEL_M(Class, API, Id)                                    \
     G_ID_HELPER_BODY(Class, Id)                                             \
     struct Class final: public cv::GKernelTypeM<Class, std::function API >, \

modules/gapi/include/opencv2/gapi/gmat.hpp

@@ -29,10 +29,24 @@ struct GOrigin;
 /** \addtogroup gapi_data_objects
  * @{
  *
- * @brief Data-representing objects which can be used to build G-API
- * expressions.
+ * @brief G-API data objects used to build G-API expressions.
+ *
+ * These objects do not own any particular data (except compile-time
+ * associated values like with cv::GScalar) and are used to construct
+ * graphs.
+ *
+ * Every graph in G-API starts and ends with data objects.
+ *
+ * Once constructed and compiled, G-API operates with regular host-side
+ * data instead. Refer to the below table to find the mapping between
+ * G-API and regular data types.
+ *
+ *    G-API data type    | I/O data type
+ *    ------------------ | -------------
+ *    cv::GMat           | cv::Mat
+ *    cv::GScalar        | cv::Scalar
+ *    `cv::GArray<T>`    | std::vector<T>
  */
-
 class GAPI_EXPORTS GMat
 {
 public:

modules/gapi/include/opencv2/gapi/gtyped.hpp

@@ -39,6 +39,46 @@ namespace detail
     auto make_default()->decltype(T{}) {return {};}
 }; // detail
 
+/**
+ * @brief This class is a typed wrapper over a regular GComputation.
+ *
+ * `std::function<>`-like template parameter specifies the graph
+ *  signature so methods so the object's constructor, methods like
+ *  `apply()` and the derived `GCompiledT::operator()` also become
+ *  typed.
+ *
+ *  There is no need to use cv::gin() or cv::gout() modifiers with
+ *  objects of this class.  Instead, all input arguments are followed
+ *  by all output arguments in the order from the template argument
+ *  signature.
+ *
+ *  Refer to the following example. Regular (untyped) code is written this way:
+ *
+ *  @snippet modules/gapi/samples/api_ref_snippets.cpp Untyped_Example
+ *
+ *  Here:
+ *
+ *  - cv::GComputation object is created with a lambda constructor
+ *    where it is defined as a two-input, one-output graph.
+ *
+ *  - Its method `apply()` in fact takes arbitrary number of arguments
+ *    (as vectors) so user can pass wrong number of inputs/outputs
+ *    here. C++ compiler wouldn't notice that since the cv::GComputation
+ *    API is polymorphic, and only a run-time error will be generated.
+ *
+ *  Now the same code written with typed API:
+ *
+ *  @snippet modules/gapi/samples/api_ref_snippets.cpp Typed_Example
+ *
+ *  The key difference is:
+ *
+ *  - Now the constructor lambda *must take* parameters and *must
+ *    return* values as defined in the `GComputationT<>` signature.
+ *  - Its method `apply()` does not require any extra specifiers to
+ *    separate input arguments from the output ones
+ *  - A `GCompiledT` (compilation product) takes input/output
+ *    arguments with no extra specifiers as well.
+ */
 template<typename> class GComputationT;
 
 // Single return value implementation

modules/gapi/include/opencv2/gapi/imgproc.hpp

@@ -17,7 +17,7 @@
 #include <opencv2/gapi/gscalar.hpp>
 
 
-/** \defgroup gapi_imgproc G-API image processing functionality
+/** \defgroup gapi_imgproc G-API Image processing functionality
 @{
     @defgroup gapi_filters Graph API: Image filters
     @defgroup gapi_colorconvert Graph API: Converting image from one color space to another

modules/gapi/include/opencv2/gapi/infer.hpp

@@ -192,6 +192,9 @@ struct GAPI_EXPORTS GNetParam {
     util::any params;    // Backend-interpreted parameter structure
 };
 
+/** \addtogroup gapi_compile_args
+ * @{
+ */
 /**
  * @brief A container class for network configurations. Similar to
  * GKernelPackage.Use cv::gapi::networks() to construct this object.
@@ -204,6 +207,7 @@ struct GAPI_EXPORTS GNetPackage {
     std::vector<GBackend> backends() const;
     std::vector<GNetParam> networks;
 };
+/** @} gapi_compile_args */
 } // namespace gapi
 
 namespace detail {

modules/gapi/include/opencv2/gapi/ocl/goclkernel.hpp

@@ -32,7 +32,7 @@ namespace gapi
 namespace ocl
 {
     /**
-     * \addtogroup gapi_std_backends G-API Standard backends
+     * \addtogroup gapi_std_backends G-API Standard Backends
      * @{
      */
     /**

modules/gapi/include/opencv2/gapi/plaidml/plaidml.hpp

@@ -18,11 +18,19 @@ namespace gapi
 namespace plaidml
 {
 
+/** \addtogroup gapi_compile_args
+ * @{
+ */
+/**
+ * @brief This structure represents the basic parameters for the experimental
+ * PlaidML backend.
+ */
 struct config
 {
-    std::string dev_id;
-    std::string trg_id;
+    std::string dev_id; //!< Device ID. Refer to PlaidML documentation for details.
+    std::string trg_id; //!< Target ID. Refer to PlaidML documentation for details.
 };
+/** @} gapi_compile_args */
 
 } // namespace plaidml
 } // namespace gapi

modules/gapi/include/opencv2/gapi/render.hpp

@@ -0,0 +1,14 @@
+// This file is part of OpenCV project.
+// It is subject to the license terms in the LICENSE file found in the top-level directory
+// of this distribution and at http://opencv.org/license.html.
+//
+// Copyright (C) 2019 Intel Corporation
+
+#ifndef OPENCV_GAPI_RENDER_ROOT_HPP
+#define OPENCV_GAPI_RENDER_ROOT_HPP
+
+// This file is just a shortcut to render/render.hpp
+
+#include <opencv2/gapi/render/render.hpp>
+
+#endif // OPENCV_GAPI_RENDER_ROOT_HPP

modules/gapi/include/opencv2/gapi/render/render.hpp

@@ -18,6 +18,56 @@
 #include <opencv2/gapi/own/exports.hpp>
 #include <opencv2/gapi/own/scalar.hpp>
 
+
+/** \defgroup gapi_draw G-API Drawing and composition functionality
+ *  @{
+ *
+ *  @brief Functions for in-graph drawing.
+ *
+ *  @note This is a Work in Progress functionality and APIs may
+ *  change in the future releases.
+ *
+ *  G-API can do some in-graph drawing with a generic operations and a
+ *  set of [rendering primitives](@ref gapi_draw_prims).
+ *  In contrast with traditional OpenCV, in G-API user need to form a
+ *  *rendering list* of primitives to draw. This list can be built
+ *  manually or generated within a graph. This list is passed to
+ *  [special operations or functions](@ref gapi_draw_api) where all
+ *  primitives are interpreted and applied to the image.
+ *
+ *  For example, in a complex pipeline a list of detected objects
+ *  can be translated in-graph to a list of cv::gapi::wip::draw::Rect
+ *  primitives to highlight those with bounding boxes, or a list of
+ *  detected faces can be translated in-graph to a list of
+ *  cv::gapi::wip::draw::Mosaic primitives to hide sensitive content
+ *  or protect privacy.
+ *
+ *  Like any other operations, rendering in G-API can be reimplemented
+ *  by different backends. Currently only an OpenCV-based backend is
+ *  available.
+ *
+ *  In addition to the graph-level operations, there are also regular
+ *  (immediate) OpenCV-like functions are available -- see
+ *  cv::gapi::wip::draw::render(). These functions are just wrappers
+ *  over regular G-API and build the rendering graphs on the fly, so
+ *  take compilation arguments as parameters.
+ *
+ *  Currently this API is more machine-oriented than human-oriented.
+ *  The main purpose is to translate a set of domain-specific objects
+ *  to a list of primitives to draw. For example, in order to generate
+ *  a picture like this:
+ *
+ *  ![](modules/gapi/doc/pics/render_example.png)
+ *
+ *  Rendering list needs to be generated as follows:
+ *
+ *  @include modules/gapi/samples/draw_example.cpp
+ *
+ *  @defgroup gapi_draw_prims Drawing primitives
+ *  @defgroup gapi_draw_api Drawing operations and functions
+ *  @}
+ */
+
 namespace cv
 {
 namespace gapi
@@ -28,17 +78,21 @@ namespace draw
 {
 
 /**
- * A structure allows using freetype library for text rendering
+ * @brief This structure specifies which FreeType font to use by FText primitives.
  */
 struct freetype_font
 {
     /*@{*/
-    std::string path; //!< The path to font file (.ttf)
+    std::string path; //!< The path to the font file (.ttf)
     /*@{*/
 };
 
+//! @addtogroup gapi_draw_prims
+//! @{
 /**
- * A structure to represent parameters for drawing a text string.
+ * @brief This structure represents a text string to draw.
+ *
+ * Parameters match cv::putText().
  */
 struct Text
 {
@@ -55,7 +109,11 @@ struct Text
 };
 
 /**
- * A structure to represent parameters for drawing a text string using FreeType library
+ * @brief This structure represents a text string to draw using
+ * FreeType renderer.
+ *
+ * If OpenCV is built without FreeType support, this primitive will
+ * fail at the execution stage.
  */
 struct FText
 {
@@ -68,7 +126,9 @@ struct FText
 };
 
 /**
- * A structure to represent parameters for drawing a rectangle
+ * @brief This structure represents a rectangle to draw.
+ *
+ * Parameters match cv::rectangle().
  */
 struct Rect
 {
@@ -80,7 +140,9 @@ struct Rect
 };
 
 /**
- * A structure to represent parameters for drawing a circle
+ * @brief This structure represents a circle to draw.
+ *
+ * Parameters match cv::circle().
  */
 struct Circle
 {
@@ -93,7 +155,9 @@ struct Circle
 };
 
 /**
- * A structure to represent parameters for drawing a line
+ * @brief This structure represents a line to draw.
+ *
+ * Parameters match cv::line().
  */
 struct Line
 {
@@ -106,17 +170,21 @@ struct Line
 };
 
 /**
- * A structure to represent parameters for drawing a mosaic
+ * @brief This structure represents a mosaicing operation.
+ *
+ * Mosaicing is a very basic method to obfuscate regions in the image.
  */
 struct Mosaic
 {
     cv::Rect   mos;    //!< Coordinates of the mosaic
-    int        cellSz; //!< Cell size (same for X, Y). Note: mos size must be multiple of cell size
+    int        cellSz; //!< Cell size (same for X, Y). Note: mosaic size must be a multiple of cell size
     int        decim;  //!< Decimation (0 stands for no decimation)
 };
 
 /**
- * A structure to represent parameters for drawing an image
+ * @brief This structure represents an image to draw.
+ *
+ * Image is blended on a frame using the specified mask.
  */
 struct Image
 {
@@ -126,7 +194,7 @@ struct Image
 };
 
 /**
- * A structure to represent parameters for drawing a polygon
+ * @brief This structure represents a polygon to draw.
  */
 struct Poly
 {
@@ -149,9 +217,14 @@ using Prim  = util::variant
     >;
 
 using Prims     = std::vector<Prim>;
+//! @} gapi_draw_prims
+
 using GMat2     = std::tuple<cv::GMat,cv::GMat>;
 using GMatDesc2 = std::tuple<cv::GMatDesc,cv::GMatDesc>;
 
+
+//! @addtogroup gapi_draw_api
+//! @{
 /** @brief The function renders on the input image passed drawing primitivies
 
 @param bgr input image: 8-bit unsigned 3-channel image @ref CV_8UC3.
@@ -211,6 +284,7 @@ uv image must be 8-bit unsigned planar 2-channel image @ref CV_8UC2
 GAPI_EXPORTS GMat2 renderNV12(const GMat& y,
                               const GMat& uv,
                               const GArray<Prim>& prims);
+//! @} gapi_draw_api
 
 } // namespace draw
 } // namespace wip
@@ -224,6 +298,15 @@ namespace ocv
 } // namespace ocv
 } // namespace render
 } // namespace gapi
+
+namespace detail
+{
+    template<> struct CompileArgTag<cv::gapi::wip::draw::freetype_font>
+    {
+        static const char* tag() { return "gapi.freetype_font"; }
+    };
+} // namespace detail
+
 } // namespace cv
 
 #endif // OPENCV_GAPI_RENDER_HPP