Merge pull request #29149 from EuropaRanger:gapi_doc_update

Gapi doc update #29149

This PR improves G-API documentation by clarifying the introduction and kernel API pages
- fixing some spelling errors
- operator|() can now link to the overloaded version that is actually called.
- supplemented and revised the doc based on the author's annotations.

The change is documentation-only and does not affect runtime behavior. I tested the doc reconstruction of this module. 

### 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

modules/gapi/doc/00-root.markdown

@@ -69,7 +69,9 @@ A very basic example of G-API pipeline is shown below:
 
 @include modules/gapi/samples/api_example.cpp
 
-<!-- TODO align this code with text using marks and itemized list -->
+The numbered flow in the sample is straightforward: the first block
+opens the video source, the second block declares the G-API graph, and
+the last block repeatedly compiles and runs that graph on each frame.
 
 G-API is a separate OpenCV module so its header files have to be
 included explicitly. The first four lines of `main()` create and
@@ -91,14 +93,14 @@ input/output data references (in this example, `in` and `out`
 cv::GMat objects, respectively) as parameters and reconstructs the
 call graph based on all the data flow between `in` and `out`.
 
-cv::GComputation is a thin object in sense that it just captures which
+cv::GComputation is a thin object in the sense that it just captures which
 operations form up a computation. However, it can be used to execute
 computations -- in the following processing loop, every captured frame (a
 cv::Mat `input_frame`) is passed to cv::GComputation::apply().
 
 ![Example pipeline running on sample video 'vtest.avi'](pics/demo.jpg)
 
-cv::GComputation::apply() is a polimorphic method which accepts a
+cv::GComputation::apply() is a polymorphic method which accepts a
 variadic number of arguments. Since this computation is defined on one
 input, one output, a special overload of cv::GComputation::apply() is
 used to pass input data and get output data.
@@ -107,19 +109,18 @@ Internally, cv::GComputation::apply() compiles the captured graph for
 the given input parameters and executes the compiled graph on data
 immediately.
 
-There is a number important concepts can be outlines with this example:
+Several important concepts are illustrated by this example:
 * Graph declaration and graph execution are distinct steps;
 * Graph is built implicitly from a sequence of G-API expressions;
 * G-API supports function-like calls -- e.g. cv::gapi::resize(), and
-  operators, e.g operator|() which is used to compute bitwise OR;
+  operators, e.g. @ref cv::operator|(const cv::GMat& lhs, const cv::GMat& rhs) "operator|()", which is used to compute bitwise OR;
 * G-API syntax aims to look pure: every operation call within a graph
   yields a new result, thus forming a directed acyclic graph (DAG);
 * Graph declaration is not bound to any data -- real data objects
   (cv::Mat) come into picture after the graph is already declared.
 
-<!-- FIXME: The above operator|() link links to MatExpr not GAPI -->
-
 See [tutorials and porting examples](@ref tutorial_table_of_content_gapi)
 to learn more on various G-API features and concepts.
 
-<!-- TODO Add chapter on declaration, compilation, execution -->
+Future revisions may split this introduction into dedicated chapters for
+declaration, compilation, and execution.

modules/gapi/doc/20-kernel-api.markdown

@@ -118,7 +118,10 @@ computation from inputs to outputs and infer metadata of internal
 for further pipeline optimizations, memory allocation, and other
 operations done by G-API framework during graph compilation.
 
-<!-- TODO add examples -->
+For example, a kernel that blurs an image can use `outMeta()` to copy
+the input image size to the output metadata while keeping the pixel
+type unchanged. A kernel that changes geometry, such as resize, updates
+the output dimensions accordingly before the graph is compiled.
 
 # Implementing a kernel {#gapi_kernel_implementing}
 
@@ -134,10 +137,10 @@ Every backend defines its own way to implement a kernel interface.
 This way is regular, though -- whatever plugin is, its kernel
 implementation must be "derived" from a kernel interface type.
 
-Kernel implementation are then organized into _kernel
-packages_. Kernel packages are passed to cv::GComputation::compile()
-as compile arguments, with some hints to G-API on how to select proper
-kernels (see more on this in "Heterogeneity"[TBD]).
+Kernel implementations are then organized into _kernel packages_.
+Kernel packages are passed to cv::GComputation::compile() as compile
+arguments, with some hints to G-API on how to select proper kernels
+according to the available backends and compilation hints.
 
 For example, the aforementioned `Filter2D` is implemented in
 "reference" CPU (OpenCV) plugin this way (*NOTE* -- this is a
@@ -176,8 +179,11 @@ macro GAPI_COMPOUND_KERNEL():
 
 @snippet samples/cpp/tutorial_code/gapi/doc_snippets/kernel_api_snippets.cpp compound
 
-<!-- TODO: ADD on how Compound kernels may simplify dispatching -->
-<!-- TODO: Add details on when expand() is called! -->
+Compound kernels can simplify dispatching because a backend may expand
+them into several smaller kernels only when that backend needs the
+decomposition. In practice, `expand()` is called during compilation,
+when G-API resolves the compound implementation into a backend-specific
+subgraph before execution.
 
 It is important to distinguish a compound kernel from G-API high-order
 function, i.e. a C++ function which looks like a kernel but in fact