G-API: Documentation updates

1) Document GFrame/MediaFrame (and also other G-API types)
- Added doxygen comments for GMat, GScalar, GArray<T>, GOpaque classes;
- Documented GFrame and its host-side counterpart MediaFrame;
- Added some more notes to the data type classes.

2) Give @brief descriptions to most of the cv::gapi::* namespaces

3) Make some symbols private
- These structures are mainly internal and shouldn't be used directly

doc/Doxyfile.in

@@ -106,7 +106,7 @@ RECURSIVE              = YES
 EXCLUDE                = @CMAKE_DOXYGEN_EXCLUDE_LIST@
 EXCLUDE_SYMLINKS       = NO
 EXCLUDE_PATTERNS       = *.inl.hpp *.impl.hpp *_detail.hpp */cudev/**/detail/*.hpp *.m */opencl/runtime/* */legacy/* *_c.h @DOXYGEN_EXCLUDE_PATTERNS@
-EXCLUDE_SYMBOLS        = cv::DataType<*> cv::traits::* int void CV__* T __CV*
+EXCLUDE_SYMBOLS        = cv::DataType<*> cv::traits::* int void CV__* T __CV* cv::gapi::detail*
 EXAMPLE_PATH           = @CMAKE_DOXYGEN_EXAMPLE_PATH@
 EXAMPLE_PATTERNS       = *
 EXAMPLE_RECURSIVE      = YES

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

@@ -29,6 +29,10 @@
  */
 
 namespace cv { namespace gapi {
+/**
+ * @brief This namespace contains G-API Operation Types for OpenCV
+ * Core module functionality.
+ */
 namespace core {
     using GMat2 = std::tuple<GMat,GMat>;
     using GMat3 = std::tuple<GMat,GMat,GMat>; // FIXME: how to avoid this?

modules/gapi/include/opencv2/gapi/cpu/gcpukernel.hpp

@@ -40,6 +40,10 @@ namespace gimpl
 
 namespace gapi
 {
+/**
+ * @brief This namespace contains G-API CPU backend functions,
+ * structures, and symbols.
+ */
 namespace cpu
 {
     /**
@@ -492,7 +496,7 @@ public:
 #define GAPI_OCV_KERNEL_ST(Name, API, State)                   \
     struct Name: public cv::GCPUStKernelImpl<Name, API, State> \
 
-
+/// @private
 class gapi::cpu::GOCVFunctor : public gapi::GFunctor
 {
 public:

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

@@ -25,6 +25,9 @@ namespace cv {
 
 namespace gapi
 {
+/**
+ * @brief This namespace contains G-API Fluid backend functions, structures, and symbols.
+ */
 namespace fluid
 {
     /**

modules/gapi/include/opencv2/gapi/garray.hpp

@@ -340,21 +340,79 @@ namespace detail
 /** \addtogroup gapi_data_objects
  * @{
  */
-
+/**
+ * @brief `cv::GArray<T>` template class represents a list of objects
+ * of class `T` in the graph.
+ *
+ * `cv::GArray<T>` describes a functional relationship between
+ * operations consuming and producing arrays of objects of class
+ * `T`. The primary purpose of `cv::GArray<T>` is to represent a
+ * dynamic list of objects -- where the size of the list is not known
+ * at the graph construction or compile time. Examples include: corner
+ * and feature detectors (`cv::GArray<cv::Point>`), object detection
+ * and tracking  results (`cv::GArray<cv::Rect>`). Programmers can use
+ * their own types with `cv::GArray<T>` in the custom operations.
+ *
+ * Similar to `cv::GScalar`, `cv::GArray<T>` may be value-initialized
+ * -- in this case a graph-constant value is associated with the object.
+ *
+ * `GArray<T>` is a virtual counterpart of `std::vector<T>`, which is
+ * usually used to represent the `GArray<T>` data in G-API during the
+ * execution.
+ *
+ * @sa `cv::GOpaque<T>`
+ */
 template<typename T> class GArray
 {
 public:
     // Host type (or Flat type) - the type this GArray is actually
     // specified to.
+    /// @private
     using HT = typename detail::flatten_g<typename std::decay<T>::type>::type;
 
+    /**
+     * @brief Constructs a value-initialized `cv::GArray<T>`
+     *
+     * `cv::GArray<T>` objects  may have their values
+     * be associated at graph construction time. It is useful when
+     * some operation has a `cv::GArray<T>` input which doesn't change during
+     * the program execution, and is set only once. In this case,
+     * there is no need to declare such `cv::GArray<T>` as a graph input.
+     *
+     * @note The value of `cv::GArray<T>` may be overwritten by assigning some
+     * other `cv::GArray<T>` to the object using `operator=` -- on the
+     * assigment, the old association or value is discarded.
+     *
+     * @param v a std::vector<T> to associate with this
+     * `cv::GArray<T>` object. Vector data is copied into the
+     * `cv::GArray<T>` (no reference to the passed data is held).
+     */
     explicit GArray(const std::vector<HT>& v) // Constant value constructor
         : m_ref(detail::GArrayU(detail::VectorRef(v))) { putDetails(); }
+
+    /**
+     * @overload
+     * @brief Constructs a value-initialized `cv::GArray<T>`
+     *
+     * @param v a std::vector<T> to associate with this
+     * `cv::GArray<T>` object. Vector data is moved into the `cv::GArray<T>`.
+     */
     explicit GArray(std::vector<HT>&& v)      // Move-constructor
         : m_ref(detail::GArrayU(detail::VectorRef(std::move(v)))) { putDetails(); }
-    GArray() { putDetails(); }             // Empty constructor
-    explicit GArray(detail::GArrayU &&ref) // GArrayU-based constructor
-        : m_ref(ref) { putDetails(); }     //   (used by GCall, not for users)
+
+    /**
+     * @brief Constructs an empty `cv::GArray<T>`
+     *
+     * Normally, empty G-API data objects denote a starting point of
+     * the graph. When an empty `cv::GArray<T>` is assigned to a result
+     * of some operation, it obtains a functional link to this
+     * operation (and is not empty anymore).
+     */
+    GArray() { putDetails(); }                // Empty constructor
+
+    /// @private
+    explicit GArray(detail::GArrayU &&ref)    // GArrayU-based constructor
+        : m_ref(ref) { putDetails(); }        //   (used by GCall, not for users)
 
     /// @private
     detail::GArrayU strip() const {

modules/gapi/include/opencv2/gapi/gasync_context.hpp

@@ -17,6 +17,13 @@
 
 namespace cv {
 namespace gapi{
+
+/**
+ * @brief This namespace contains experimental G-API functionality,
+ * functions or structures in this namespace are subjects to change or
+ * removal in the future releases. This namespace also contains
+ * functions which API is not stabilized yet.
+ */
 namespace wip {
 
 /**

modules/gapi/include/opencv2/gapi/gframe.hpp

@@ -28,14 +28,54 @@ struct GOrigin;
 /** \addtogroup gapi_data_objects
  * @{
  */
+/**
+ * @brief GFrame class represents an image or media frame in the graph.
+ *
+ * GFrame doesn't store any data itself, instead it describes a
+ * functional relationship between operations consuming and producing
+ * GFrame objects.
+ *
+ * GFrame is introduced to handle various media formats (e.g., NV12 or
+ * I420) under the same type. Various image formats may differ in the
+ * number of planes (e.g. two for NV12, three for I420) and the pixel
+ * layout inside. GFrame type allows to handle these media formats in
+ * the graph uniformly -- the graph structure will not change if the
+ * media format changes, e.g. a different camera or decoder is used
+ * with the same graph. G-API provides a number of operations which
+ * operate directly on GFrame, like `infer<>()` or
+ * renderFrame(); these operations are expected to handle different
+ * media formats inside. There is also a number of accessor
+ * operations like BGR(), Y(), UV() -- these operations provide
+ * access to frame's data in the familiar cv::GMat form, which can be
+ * used with the majority of the existing G-API operations. These
+ * accessor functions may perform color space converion on the fly if
+ * the image format of the GFrame they are applied to differs from the
+ * operation's semantic (e.g. the BGR() accessor is called on an NV12
+ * image frame).
+ *
+ * GFrame is a virtual counterpart of cv::MediaFrame.
+ *
+ * @sa cv::MediaFrame, cv::GFrameDesc, BGR(), Y(), UV(), infer<>().
+ */
 class GAPI_EXPORTS_W_SIMPLE GFrame
 {
 public:
-    GAPI_WRAP GFrame();                       // Empty constructor
-    GFrame(const GNode &n, std::size_t out);  // Operation result constructor
+    /**
+     * @brief Constructs an empty GFrame
+     *
+     * Normally, empty G-API data objects denote a starting point of
+     * the graph. When an empty GFrame is assigned to a result of some
+     * operation, it obtains a functional link to this operation (and
+     * is not empty anymore).
+     */
+    GAPI_WRAP GFrame();                      // Empty constructor
 
-    GOrigin& priv();                        // Internal use only
-    const GOrigin& priv()  const;           // Internal use only
+    /// @private
+    GFrame(const GNode &n, std::size_t out); // Operation result constructor
+    /// @private
+    GOrigin& priv();                         // Internal use only
+    /// @private
+    const GOrigin& priv()  const;            // Internal use only
 
 private:
     std::shared_ptr<GOrigin> m_priv;

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

@@ -372,6 +372,7 @@ namespace gapi
 {
     // Prework: model "Device" API before it gets to G-API headers.
     // FIXME: Don't mix with internal Backends class!
+    /// @private
     class GAPI_EXPORTS GBackend
     {
     public:
@@ -412,6 +413,7 @@ namespace std
 
 namespace cv {
 namespace gapi {
+    /// @private
     class GFunctor
     {
     public:

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

@@ -30,29 +30,57 @@ struct GOrigin;
  * @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.
+ * associated values like with cv::GScalar or `cv::GArray<T>`) and are
+ * used only 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 and regular data types when passing input and output data
+ * structures to G-API:
  *
  *    G-API data type    | I/O data type
  *    ------------------ | -------------
- *    cv::GMat           | cv::Mat
+ *    cv::GMat           | cv::Mat, cv::UMat, cv::RMat
  *    cv::GScalar        | cv::Scalar
  *    `cv::GArray<T>`    | std::vector<T>
  *    `cv::GOpaque<T>`   | T
+ *    cv::GFrame         | cv::MediaFrame
+ */
+/**
+ * @brief GMat class represents image or tensor data in the
+ * graph.
+ *
+ * GMat doesn't store any data itself, instead it describes a
+ * functional relationship between operations consuming and producing
+ * GMat objects.
+ *
+ * GMat is a virtual counterpart of Mat and UMat, but it
+ * doesn't mean G-API use Mat or UMat objects internally to represent
+ * GMat objects -- the internal data representation may be
+ * backend-specific or optimized out at all.
+ *
+ * @sa Mat, GMatDesc
  */
 class GAPI_EXPORTS_W_SIMPLE GMat
 {
 public:
+    /**
+     * @brief Constructs an empty GMat
+     *
+     * Normally, empty G-API data objects denote a starting point of
+     * the graph. When an empty GMat is assigned to a result of some
+     * operation, it obtains a functional link to this operation (and
+     * is not empty anymore).
+     */
     GAPI_WRAP GMat();                       // Empty constructor
-    GMat(const GNode &n, std::size_t out);  // Operation result constructor
 
+    /// @private
+    GMat(const GNode &n, std::size_t out);  // Operation result constructor
+    /// @private
     GOrigin& priv();                        // Internal use only
+    /// @private
     const GOrigin& priv()  const;           // Internal use only
 
 private:

modules/gapi/include/opencv2/gapi/gopaque.hpp

@@ -307,15 +307,40 @@ namespace detail
 /** \addtogroup gapi_data_objects
  * @{
  */
-
+/**
+ * @brief `cv::GOpaque<T>` template class represents an object of
+ * class `T` in the graph.
+ *
+ * `cv::GOpaque<T>` describes a functional relationship between operations
+ * consuming and producing object of class `T`. `cv::GOpaque<T>` is
+ * designed to extend G-API with user-defined data types, which are
+ * often required with user-defined operations. G-API can't apply any
+ * optimizations to user-defined types since these types are opaque to
+ * the framework. However, there is a number of G-API operations
+ * declared with `cv::GOpaque<T>` as a return type,
+ * e.g. cv::gapi::streaming::timestamp() or cv::gapi::streaming::size().
+ *
+ * @sa `cv::GArray<T>`
+ */
 template<typename T> class GOpaque
 {
 public:
     // Host type (or Flat type) - the type this GOpaque is actually
     // specified to.
+    /// @private
     using HT = typename detail::flatten_g<util::decay_t<T>>::type;
 
+    /**
+     * @brief Constructs an empty `cv::GOpaque<T>`
+     *
+     * Normally, empty G-API data objects denote a starting point of
+     * the graph. When an empty `cv::GOpaque<T>` is assigned to a result
+     * of some operation, it obtains a functional link to this
+     * operation (and is not empty anymore).
+     */
     GOpaque() { putDetails(); }              // Empty constructor
+
+    /// @private
     explicit GOpaque(detail::GOpaqueU &&ref) // GOpaqueU-based constructor
         : m_ref(ref) { putDetails(); }       // (used by GCall, not for users)
 

modules/gapi/include/opencv2/gapi/gscalar.hpp

@@ -25,18 +25,83 @@ struct GOrigin;
 /** \addtogroup gapi_data_objects
  * @{
  */
-
+/**
+ * @brief GScalar class represents cv::Scalar data in the graph.
+ *
+ * GScalar may be associated with a cv::Scalar value, which becomes
+ * its constant value bound in graph compile time. cv::GScalar describes a
+ * functional relationship between operations consuming and producing
+ * GScalar objects.
+ *
+ * GScalar is a virtual counterpart of cv::Scalar, which is usually used
+ * to represent the GScalar data in G-API during the execution.
+ *
+ * @sa Scalar
+ */
 class GAPI_EXPORTS_W_SIMPLE GScalar
 {
 public:
-    GAPI_WRAP GScalar();                    // Empty constructor
-    explicit GScalar(const cv::Scalar& s);  // Constant value constructor from cv::Scalar
+    /**
+     * @brief Constructs an empty GScalar
+     *
+     * Normally, empty G-API data objects denote a starting point of
+     * the graph. When an empty GScalar is assigned to a result of some
+     * operation, it obtains a functional link to this operation (and
+     * is not empty anymore).
+     */
+    GAPI_WRAP GScalar();
+
+    /**
+     * @brief Constructs a value-initialized GScalar
+     *
+     * In contrast with GMat (which can be either an explicit graph input
+     * or a result of some operation), GScalars may have their values
+     * be associated at graph construction time. It is useful when
+     * some operation has a GScalar input which doesn't change during
+     * the program execution, and is set only once. In this case,
+     * there is no need to declare such GScalar as a graph input.
+     *
+     * @note The value of GScalar may be overwritten by assigning some
+     * other GScalar to the object using `operator=` -- on the
+     * assigment, the old GScalar value is discarded.
+     *
+     * @param s a cv::Scalar value to associate with this GScalar object.
+     */
+    explicit GScalar(const cv::Scalar& s);
+
+    /**
+     * @overload
+     * @brief Constructs a value-initialized GScalar
+     *
+     * @param s a cv::Scalar value to associate with this GScalar object.
+     */
     explicit GScalar(cv::Scalar&& s);       // Constant value move-constructor from cv::Scalar
 
+    /**
+     * @overload
+     * @brief Constructs a value-initialized GScalar
+     *
+     * @param v0 A `double` value to associate with this GScalar. Note
+     *  that only the first component of a four-component cv::Scalar is
+     *  set to this value, with others remain zeros.
+     *
+     * This constructor overload is not marked `explicit` and can be
+     * used in G-API expression code like this:
+     *
+     * @snippet modules/gapi/samples/api_ref_snippets.cpp gscalar_implicit
+     *
+     * Here operator+(GMat,GScalar) is used to wrap cv::gapi::addC()
+     * and a value-initialized GScalar is created on the fly.
+     *
+     * @overload
+     */
     GScalar(double v0);                                // Constant value constructor from double
-    GScalar(const GNode &n, std::size_t out);          // Operation result constructor
 
+    /// @private
+    GScalar(const GNode &n, std::size_t out);          // Operation result constructor
+    /// @private
     GOrigin& priv();                                   // Internal use only
+    /// @private
     const GOrigin& priv()  const;                      // Internal use only
 
 private:

modules/gapi/include/opencv2/gapi/gstreaming.hpp

@@ -372,6 +372,14 @@ protected:
 /** @} */
 
 namespace gapi {
+
+/**
+ * @brief This namespace contains G-API functions, structures, and
+ * symbols related to the Streaming execution mode.
+ *
+ * Some of the operations defined in this namespace (e.g. size(),
+ * BGR(), etc.) can be used in the traditional execution mode too.
+ */
 namespace streaming {
 /**
  * @brief Specify queue capacity for streaming execution.

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

@@ -47,6 +47,10 @@ void validateFindingContoursMeta(const int depth, const int chan, const int mode
 
 namespace cv { namespace gapi {
 
+/**
+ * @brief This namespace contains G-API Operation Types for OpenCV
+ * ImgProc module functionality.
+ */
 namespace imgproc {
     using GMat2 = std::tuple<GMat,GMat>;
     using GMat3 = std::tuple<GMat,GMat,GMat>; // FIXME: how to avoid this?

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

@@ -653,6 +653,7 @@ namespace gapi {
 
 // A type-erased form of network parameters.
 // Similar to how a type-erased GKernel is represented and used.
+/// @private
 struct GAPI_EXPORTS GNetParam {
     std::string tag;     // FIXME: const?
     GBackend backend;    // Specifies the execution model
@@ -664,7 +665,7 @@ struct GAPI_EXPORTS GNetParam {
  */
 /**
  * @brief A container class for network configurations. Similar to
- * GKernelPackage.Use cv::gapi::networks() to construct this object.
+ * GKernelPackage. Use cv::gapi::networks() to construct this object.
  *
  * @sa cv::gapi::networks
  */

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

@@ -24,6 +24,11 @@
 namespace cv {
 namespace gapi {
 // FIXME: introduce a new sub-namespace for NN?
+
+/**
+ * @brief This namespace contains G-API OpenVINO backend functions,
+ * structures, and symbols.
+ */
 namespace ie {
 
 GAPI_EXPORTS cv::gapi::GBackend backend();

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

@@ -20,6 +20,10 @@
 
 namespace cv {
 namespace gapi {
+
+/**
+ * @brief This namespace contains G-API ONNX Runtime backend functions, structures, and symbols.
+ */
 namespace onnx {
 
 GAPI_EXPORTS cv::gapi::GBackend backend();

modules/gapi/include/opencv2/gapi/media.hpp

@@ -17,28 +17,107 @@
 
 namespace cv {
 
+/** \addtogroup gapi_data_structures
+ * @{
+ *
+ * @brief Extra G-API data structures used to pass input/output data
+ * to the graph for processing.
+ */
+/**
+ * @brief cv::MediaFrame class represents an image/media frame
+ * obtained from an external source.
+ *
+ * cv::MediaFrame represents image data as specified in
+ * cv::MediaFormat. cv::MediaFrame is designed to be a thin wrapper over some
+ * external memory of buffer; the class itself provides an uniform
+ * interface over such types of memory. cv::MediaFrame wraps data from
+ * a camera driver or from a media codec and provides an abstraction
+ * layer over this memory to G-API. MediaFrame defines a compact interface
+ * to access and manage the underlying data; the implementation is
+ * fully defined by the associated Adapter (which is usually
+ * user-defined).
+ *
+ * @sa cv::RMat
+ */
 class GAPI_EXPORTS MediaFrame {
 public:
-    enum class Access { R, W };
+    /// This enum defines different types of cv::MediaFrame provided
+    /// access to the underlying data. Note that different flags can't
+    /// be combined in this version.
+    enum class Access {
+        R, ///< Access data for reading
+        W, ///< Access data for writing
+    };
     class IAdapter;
     class View;
     using AdapterPtr = std::unique_ptr<IAdapter>;
 
+    /**
+     * @brief Constructs an empty MediaFrame
+     *
+     * The constructed object has no any data associated with it.
+     */
     MediaFrame();
-    explicit MediaFrame(AdapterPtr &&);
-    template<class T, class... Args> static cv::MediaFrame Create(Args&&...);
 
-    View access(Access) const;
+    /**
+     * @brief Constructs a MediaFrame with the given
+     * Adapter. MediaFrame takes ownership over the passed adapter.
+     *
+     * @param p an unique pointer to instance of IAdapter derived class.
+     */
+    explicit MediaFrame(AdapterPtr &&p);
+
+    /**
+     * @overload
+     * @brief Constructs a MediaFrame with the given parameters for
+     * the Adapter. The adapter of type `T` is costructed on the fly.
+     *
+     * @param args list of arguments to construct an adapter of type
+     * `T`.
+     */
+    template<class T, class... Args> static cv::MediaFrame Create(Args&&... args);
+
+    /**
+     * @brief Obtain access to the underlying data with the given
+     * mode.
+     *
+     * Depending on the associated Adapter and the data wrapped, this
+     * method may be cheap (e.g., the underlying memory is local) or
+     * costly (if the underlying memory is external or device
+     * memory).
+     *
+     * @param mode an access mode flag
+     * @return a MediaFrame::View object. The views should be handled
+     * carefully, refer to the MediaFrame::View documentation for details.
+     */
+    View access(Access mode) const;
+
+    /**
+     * @brief Returns a media frame descriptor -- the information
+     * about the media format, dimensions, etc.
+     * @return a cv::GFrameDesc
+     */
     cv::GFrameDesc desc() const;
 
     // FIXME: design a better solution
     // Should be used only if the actual adapter provides implementation
+    /// @private -- exclude from the OpenCV documentation for now.
     cv::util::any blobParams() const;
 
-    // Cast underlying MediaFrame adapter to the particular adapter type,
-    // return nullptr if underlying type is different
-    template<typename T> T* get() const
-    {
+    /**
+     * @brief Casts and returns the associated MediaFrame adapter to
+     * the particular adapter type `T`, returns nullptr if the type is
+     * different.
+     *
+     * This method may be useful if the adapter type is known by the
+     * caller, and some lower level access to the memory is required.
+     * Depending on the memory type, it may be more efficient than
+     * access().
+     *
+     * @return a pointer to the adapter object, nullptr if the adapter
+     * type is different.
+     */
+    template<typename T> T* get() const {
         static_assert(std::is_base_of<IAdapter, T>::value,
                       "T is not derived from cv::MediaFrame::IAdapter!");
         auto* adapter = getAdapter();
@@ -58,6 +137,43 @@ inline cv::MediaFrame cv::MediaFrame::Create(Args&&... args) {
     return cv::MediaFrame(std::move(ptr));
 }
 
+/**
+ * @brief Provides access to the MediaFrame's underlying data.
+ *
+ * This object contains the necessary information to access the pixel
+ * data of the associated MediaFrame: arrays of pointers and strides
+ * (distance between every plane row, in bytes) for every image
+ * plane, as defined in cv::MediaFormat.
+ * There may be up to four image planes in MediaFrame.
+ *
+ * Depending on the MediaFrame::Access flag passed in
+ * MediaFrame::access(), a MediaFrame::View may be read- or
+ * write-only.
+ *
+ * Depending on the MediaFrame::IAdapter implementation associated
+ * with the parent MediaFrame, writing to memory with
+ * MediaFrame::Access::R flag may have no effect or lead to
+ * undefined behavior. Same applies to reading the memory with
+ * MediaFrame::Access::W flag -- again, depending on the IAdapter
+ * implementation, the host-side buffer the view provides access to
+ * may have no current data stored in (so in-place editing of the
+ * buffer contents may not be possible).
+ *
+ * MediaFrame::View objects must be handled carefully, as an external
+ * resource associated with MediaFrame may be locked for the time the
+ * MediaFrame::View object exists. Obtaining MediaFrame::View should
+ * be seen as "map" and destroying it as "unmap" in the "map/unmap"
+ * idiom (applicable to OpenCL, device memory, remote
+ * memory).
+ *
+ * When a MediaFrame buffer is accessed for writing, and the memory
+ * under MediaFrame::View::Ptrs is altered, the data synchronization
+ * of a host-side and device/remote buffer is not guaranteed until the
+ * MediaFrame::View is destroyed. In other words, the real data on the
+ * device or in a remote target may be updated at the MediaFrame::View
+ * destruction only -- but it depends on the associated
+ * MediaFrame::IAdapter implementation.
+ */
 class GAPI_EXPORTS MediaFrame::View final {
 public:
     static constexpr const size_t MAX_PLANES = 4;
@@ -65,19 +181,38 @@ public:
     using Strides  = std::array<std::size_t, MAX_PLANES>; // in bytes
     using Callback = std::function<void()>;
 
+    /// @private
     View(Ptrs&& ptrs, Strides&& strs, Callback &&cb = [](){});
+
+    /// @private
     View(const View&) = delete;
+
+    /// @private
     View(View&&) = default;
+
+    /// @private
     View& operator = (const View&) = delete;
+
     ~View();
 
-    Ptrs    ptr;
-    Strides stride;
+    Ptrs    ptr; ///< Array of image plane pointers
+    Strides stride; ///< Array of image plane strides, in bytes.
 
 private:
     Callback m_cb;
 };
 
+/**
+ * @brief An interface class for MediaFrame data adapters.
+ *
+ * Implement this interface to wrap media data in the MediaFrame. It
+ * makes sense to implement this class if there is a custom
+ * cv::gapi::wip::IStreamSource defined -- in this case, a stream
+ * source can produce MediaFrame objects with this adapter and the
+ * media data may be passed to graph without any copy. For example, a
+ * GStreamer-based stream source can implement an adapter over
+ * `GstBuffer` and G-API will transparently use it in the graph.
+ */
 class GAPI_EXPORTS MediaFrame::IAdapter {
 public:
     virtual ~IAdapter() = 0;
@@ -87,6 +222,7 @@ public:
     // The default implementation does nothing
     virtual cv::util::any blobParams() const;
 };
+/** @} */
 
 } //namespace cv
 

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

@@ -29,6 +29,9 @@ namespace gimpl
 
 namespace gapi
 {
+/**
+ * @brief This namespace contains G-API OpenCL backend functions, structures, and symbols.
+ */
 namespace ocl
 {
     /**

modules/gapi/include/opencv2/gapi/own/types.hpp

@@ -15,6 +15,11 @@ namespace cv
 {
 namespace gapi
 {
+
+/**
+ * @brief This namespace contains G-API own data structures used in
+ * its standalone mode build.
+ */
 namespace own
 {
 

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

@@ -15,6 +15,11 @@ namespace cv
 {
 namespace gapi
 {
+
+/**
+ * @brief This namespace contains G-API PlaidML backend functions,
+ * structures, and symbols.
+ */
 namespace plaidml
 {
 

modules/gapi/include/opencv2/gapi/python/python.hpp

@@ -13,6 +13,15 @@
 
 namespace cv {
 namespace gapi {
+
+/**
+ * @brief This namespace contains G-API Python backend functions,
+ * structures, and symbols.
+ *
+ * This functionality is required to enable G-API custom operations
+ * and kernels when using G-API from Python, no need to use it in the
+ * C++ form.
+ */
 namespace python {
 
 GAPI_EXPORTS cv::gapi::GBackend backend();

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

@@ -169,6 +169,10 @@ GAPI_EXPORTS GFrame renderFrame(const GFrame& m_frame,
 } // namespace draw
 } // namespace wip
 
+/**
+ * @brief This namespace contains G-API CPU rendering backend functions,
+ * structures, and symbols. See @ref gapi_draw for details.
+ */
 namespace render
 {
 namespace ocv

modules/gapi/include/opencv2/gapi/rmat.hpp

@@ -42,6 +42,9 @@ namespace cv {
 //         performCalculations(in_view, out_view);
 //         // data from out_view is transferred to the device when out_view is destroyed
 //     }
+/** \addtogroup gapi_data_structures
+ * @{
+ */
 class GAPI_EXPORTS RMat
 {
 public:
@@ -146,6 +149,7 @@ private:
 
 template<typename T, typename... Ts>
 RMat make_rmat(Ts&&... args) { return { std::make_shared<T>(std::forward<Ts>(args)...) }; }
+/** @} */
 
 } //namespace cv
 

modules/gapi/include/opencv2/gapi/s11n/base.hpp

@@ -12,6 +12,11 @@
 
 namespace cv {
 namespace gapi {
+
+/**
+ * @brief This namespace contains G-API serialization and
+ * deserialization functions and data structures.
+ */
 namespace s11n {
 struct IOStream;
 struct IIStream;

modules/gapi/include/opencv2/gapi/stereo.hpp

@@ -21,6 +21,11 @@ enum class StereoOutputFormat {
     DISPARITY_FIXED16_12_4
 };
 
+
+/**
+ * @brief This namespace contains G-API Operation Types for Stereo and
+ * related functionality.
+ */
 namespace calib3d {
 
 G_TYPED_KERNEL(GStereo, <GMat(GMat, GMat, const StereoOutputFormat)>, "org.opencv.stereo") {

modules/gapi/include/opencv2/gapi/video.hpp

@@ -42,6 +42,10 @@ struct GAPI_EXPORTS KalmanParams
     Mat controlMatrix;
 };
 
+/**
+ * @brief This namespace contains G-API Operations and functions for
+ * video-oriented algorithms, like optical flow and background subtraction.
+ */
 namespace  video
 {
 using GBuildPyrOutput  = std::tuple<GArray<GMat>, GScalar>;

modules/gapi/samples/api_ref_snippets.cpp

@@ -9,6 +9,14 @@
 #include <opencv2/gapi/fluid/core.hpp>
 #include <opencv2/gapi/fluid/imgproc.hpp>
 
+static void gscalar_example()
+{
+    //! [gscalar_implicit]
+    cv::GMat a;
+    cv::GMat b = a + 1;
+    //! [gscalar_implicit]
+}
+
 static void typed_example()
 {
     const cv::Size sz(32, 32);
@@ -116,7 +124,9 @@ int main(int argc, char *argv[])
         >();
     //! [kernels_snippet]
 
-    // Just call typed example with no input/output
+    // Just call typed example with no input/output - avoid warnings about
+    // unused functions
     typed_example();
+    gscalar_example();
     return 0;
 }

modules/gapi/samples/gaze_estimation.cpp

@@ -16,13 +16,13 @@ const std::string keys =
     "{ h help |                                    | Print this help message }"
     "{ input  |                                    | Path to the input video file }"
     "{ facem  | face-detection-retail-0005.xml     | Path to OpenVINO face detection model (.xml) }"
-    "{ faced  | CPU                                | Target device for the face detection (e.g. CPU, GPU, VPU, ...) }"
+    "{ faced  | CPU                                | Target device for the face detection (e.g. CPU, GPU, ...) }"
     "{ landm  | facial-landmarks-35-adas-0002.xml  | Path to OpenVINO landmarks detector model (.xml) }"
-    "{ landd  | CPU                                | Target device for the landmarks detector (e.g. CPU, GPU, VPU, ...) }"
+    "{ landd  | CPU                                | Target device for the landmarks detector (e.g. CPU, GPU, ...) }"
     "{ headm  | head-pose-estimation-adas-0001.xml | Path to OpenVINO head pose estimation model (.xml) }"
-    "{ headd  | CPU                                | Target device for the head pose estimation inference (e.g. CPU, GPU, VPU, ...) }"
+    "{ headd  | CPU                                | Target device for the head pose estimation inference (e.g. CPU, GPU, ...) }"
     "{ gazem  | gaze-estimation-adas-0002.xml      | Path to OpenVINO gaze vector estimaiton model (.xml) }"
-    "{ gazed  | CPU                                | Target device for the gaze vector estimation inference (e.g. CPU, GPU, VPU, ...) }"
+    "{ gazed  | CPU                                | Target device for the gaze vector estimation inference (e.g. CPU, GPU, ...) }"
     ;
 
 namespace {
@@ -338,7 +338,7 @@ int main(int argc, char *argv[])
 
     cv::GMat in;
     cv::GMat faces = cv::gapi::infer<custom::Faces>(in);
-    cv::GOpaque<cv::Size> sz = custom::Size::on(in); // FIXME
+    cv::GOpaque<cv::Size> sz = cv::gapi::streaming::size(in);
     cv::GArray<cv::Rect> faces_rc = custom::ParseSSD::on(faces, sz, true);
     cv::GArray<cv::GMat> angles_y, angles_p, angles_r;
     std::tie(angles_y, angles_p, angles_r) = cv::gapi::infer<custom::HeadPose>(faces_rc, in);