From bdc8e9118b720116610092e202044e717c76008e Mon Sep 17 00:00:00 2001
From: Anatoliy Talamanov <anatoliy.talamanov@intel.com>
Date: Tue, 8 Jun 2021 11:59:57 +0300
Subject: [PATCH] Merge pull request #20169 from
 TolyaTalamanov:at/doc-generic-type

[G-API] Generic type documentation

* Put doc about generic type

* Fix comments to review
---
 modules/gapi/include/opencv2/gapi/infer.hpp   |  6 ++-
 .../gapi/include/opencv2/gapi/infer/ie.hpp    | 50 ++++++++++++++++---
 2 files changed, 47 insertions(+), 9 deletions(-)

diff --git a/modules/gapi/include/opencv2/gapi/infer.hpp b/modules/gapi/include/opencv2/gapi/infer.hpp
index 7ba3a44881..eb9b9768c9 100644
--- a/modules/gapi/include/opencv2/gapi/infer.hpp
+++ b/modules/gapi/include/opencv2/gapi/infer.hpp
@@ -531,7 +531,11 @@ typename Net::Result infer(Args&&... args) {
 }
 
 /**
- * @brief Special network type
+ * @brief Generic network type: input and output layers are configured dynamically at runtime
+ *
+ * Unlike the network types defined with G_API_NET macro, this one
+ * doesn't fix number of network inputs and outputs at the compilation stage
+ * thus providing user with an opportunity to program them in runtime.
  */
 struct Generic { };
 
diff --git a/modules/gapi/include/opencv2/gapi/infer/ie.hpp b/modules/gapi/include/opencv2/gapi/infer/ie.hpp
index 2bed13abc3..5b614de363 100644
--- a/modules/gapi/include/opencv2/gapi/infer/ie.hpp
+++ b/modules/gapi/include/opencv2/gapi/infer/ie.hpp
@@ -196,9 +196,24 @@ protected:
     detail::ParamDesc desc;
 };
 
+/*
+* @brief This structure provides functions for generic network type that
+* fill inference parameters.
+* @see struct Generic
+*/
 template<>
 class Params<cv::gapi::Generic> {
 public:
+    /** @brief Class constructor.
+
+    Constructs Params based on model information and sets default values for other
+    inference description parameters. Model is loaded and compiled using OpenVINO Toolkit.
+
+    @param tag string tag of the network for which these parameters are intended.
+    @param model path to topology IR (.xml file).
+    @param weights path to weights (.bin file).
+    @param device target device to use.
+    */
     Params(const std::string &tag,
            const std::string &model,
            const std::string &weights,
@@ -206,22 +221,34 @@ public:
         : desc{ model, weights, device, {}, {}, {}, 0u, 0u, detail::ParamDesc::Kind::Load, true, {}, {}, {}, 1u}, m_tag(tag) {
     };
 
+    /** @overload
+
+    This constructor for pre-compiled networks. Model is imported from pre-compiled
+    blob.
+
+    @param tag string tag of the network for which these parameters are intended.
+    @param model path to model.
+    @param device target device to use.
+    */
     Params(const std::string &tag,
            const std::string &model,
            const std::string &device)
         : desc{ model, {}, device, {}, {}, {}, 0u, 0u, detail::ParamDesc::Kind::Import, true, {}, {}, {}, 1u}, m_tag(tag) {
     };
 
-    Params& pluginConfig(IEConfig&& cfg) {
-        desc.config = std::move(cfg);
+    /** @see ie::Params::pluginConfig. */
+    Params& pluginConfig(const IEConfig& cfg) {
+        desc.config = cfg;
         return *this;
     }
 
-    Params& pluginConfig(const IEConfig& cfg) {
-        desc.config = cfg;
+    /** @overload */
+    Params& pluginConfig(IEConfig&& cfg) {
+        desc.config = std::move(cfg);
         return *this;
     }
 
+    /** @see ie::Params::constInput. */
     Params& constInput(const std::string &layer_name,
                        const cv::Mat &data,
                        TraitAs hint = TraitAs::TENSOR) {
@@ -229,37 +256,44 @@ public:
         return *this;
     }
 
+    /** @see ie::Params::cfgNumRequests. */
     Params& cfgNumRequests(size_t nireq) {
         GAPI_Assert(nireq > 0 && "Number of infer requests must be greater than zero!");
         desc.nireq = nireq;
         return *this;
     }
 
-    Params& cfgInputReshape(std::map<std::string, std::vector<std::size_t>> && reshape_table) {
-        desc.reshape_table = std::move(reshape_table);
+    /** @see ie::Params::cfgInputReshape */
+    Params& cfgInputReshape(const std::map<std::string, std::vector<std::size_t>>&reshape_table) {
+        desc.reshape_table = reshape_table;
         return *this;
     }
 
-    Params& cfgInputReshape(const std::map<std::string, std::vector<std::size_t>>&reshape_table) {
-        desc.reshape_table = reshape_table;
+    /** @overload */
+    Params& cfgInputReshape(std::map<std::string, std::vector<std::size_t>> && reshape_table) {
+        desc.reshape_table = std::move(reshape_table);
         return *this;
     }
 
+    /** @overload */
     Params& cfgInputReshape(std::string && layer_name, std::vector<size_t> && layer_dims) {
         desc.reshape_table.emplace(layer_name, layer_dims);
         return *this;
     }
 
+    /** @overload */
     Params& cfgInputReshape(const std::string & layer_name, const std::vector<size_t>&layer_dims) {
         desc.reshape_table.emplace(layer_name, layer_dims);
         return *this;
     }
 
+    /** @overload */
     Params& cfgInputReshape(std::unordered_set<std::string> && layer_names) {
         desc.layer_names_to_reshape = std::move(layer_names);
         return *this;
     }
 
+    /** @overload */
     Params& cfgInputReshape(const std::unordered_set<std::string>&layer_names) {
         desc.layer_names_to_reshape = layer_names;
         return *this;