G-API: add documentation on serialization functionality by smirnov-alexey · Pull Request #20163 · opencv/opencv

smirnov-alexey · 2021-05-26T16:16:44Z

Docs: http://pullrequest.opencv.org/buildbot/export/pr/20163/docs/

Pull Request Readiness Checklist

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

I agree to contribute to the project under Apache 2 License.
To the best of my knowledge, the proposed patch is not based on a code under GPL or other license that is incompatible with OpenCV
The PR is proposed to proper branch
There is reference to 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

force_builders=Custom,Custom Win,Custom Mac
build_gapi_standalone:Linux x64=ade-0.1.1f
build_gapi_standalone:Win64=ade-0.1.1f
build_gapi_standalone:Mac=ade-0.1.1f
build_gapi_standalone:Linux x64 Debug=ade-0.1.1f

Xbuild_image:Custom=centos:7
Xbuildworker:Custom=linux-1
build_gapi_standalone:Custom=ade-0.1.1f

build_image:Custom=ubuntu-openvino-2021.3.0:20.04
build_image:Custom Win=openvino-2021.3.0
build_image:Custom Mac=openvino-2021.3.0

test_modules:Custom=gapi,python2,python3,java
test_modules:Custom Win=gapi,python2,python3,java
test_modules:Custom Mac=gapi,python2,python3,java

buildworker:Custom=linux-1
# disabled due high memory usage: test_opencl:Custom=ON
test_opencl:Custom=OFF
test_bigdata:Custom=1
test_filter:Custom=*

smirnov-alexey · 2021-05-26T16:20:25Z

@dmatveev @TolyaTalamanov @mpashchenkov please, review. Not sure if I need to add more examples (for instance, on S11N overload). Actually, I didn't document everything in s11n.hpp since it's not for user to utilize. However, bind() is also not quite for end users (rather for our backends development). What do you think?

smirnov-alexey · 2021-06-03T10:10:06Z

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

+ * @return deserialized GComputation object.
+ */
 template<> inline
 cv::GComputation deserialize(const std::vector<char> &p) {


@alalek could you help a little? Do you know how to correctly document template specialization (or whatever the issue causes docs corruption)? Currently it looks like this: https://pullrequest.opencv.org/buildbot/export/pr/20163/docs/db/d06/group__gapi__serialization.html

I believe it looks ok in your example - isn't it?

(I see only two derializes there though)

Let's ignore this for now. I will create a separate task to fix it later

dmatveev

Good start

modules/gapi/include/opencv2/gapi/garg.hpp

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

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

smirnov-alexey · 2021-06-18T14:10:56Z

@TolyaTalamanov @mpashchenkov please, take a look once the doc build is ready

…i_serialization_docs

mpashchenkov

Overall looks good.

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

TolyaTalamanov · 2021-06-23T09:27:49Z

modules/gapi/samples/bind_after_deserialization_example.cpp

+
+int main(int argc, char *argv[])
+{
+    (void) argc;


Why don't use int main() instead ?

smirnov-alexey · 2021-06-23T13:19:24Z

@alalek can we merge this?

alalek · 2021-06-24T09:56:33Z

modules/gapi/samples/bind_after_deserialization_example.cpp

+#include <opencv2/gapi/garg.hpp>
+
+int main()
+{


modules/gapi/samples

It makes sense to put these documentation-only non-functional samples somewhere else.

@alalek I believe gapi/samples is the only place for such things - it provides examples for docs (via @snippet) and also checks that the code compiles

OpenCV 'core' snippets are stored into <opencv>/samples/cpp/tutorial_code/core/...

Users expecting in gapi/samples full-functional samples which can be run and show some meanungful result.

examples for docs

Check generated Doxyfile - there are many paths for storing that.

@snippet custom_type_serialization.cpp

This filename is not enough to be unique across whole project (other cases have similar problem).
Use path with gapi entry (append path prefix) to avoid ambiguous problem in the future.

@alalek I fixed the prefixes where applicable. Speaking of an appropriate place for these snippets: I've found 2 incomplete samples in g-api: dynamic_graph.cpp and kernel_api_snippets.cpp. I've copied std::cout << "This sample is non-complete. It is used as code snippents in documentation." << std::endl; to my samples. Is that enough? If you think that's still an issue can it be fixed separately?

Also, can we merge this without a second Dmitry's review?

It makes sense to put these documentation-only non-functional samples somewhere else.

@alalek , Our documentation-related code (so it is "snippets) was there from the early beginning but if there's a better place, we can move it there for sure for all the snippets.

modules/gapi/include/opencv2/gapi/garg.hpp

alalek · 2021-06-25T10:56:32Z

modules/gapi/samples/bind_after_deserialization_example.cpp

+#include <opencv2/gapi/garg.hpp>
+
+int main()
+{


OpenCV 'core' snippets are stored into <opencv>/samples/cpp/tutorial_code/core/...

Users expecting in gapi/samples full-functional samples which can be run and show some meanungful result.

examples for docs

Check generated Doxyfile - there are many paths for storing that.

@snippet custom_type_serialization.cpp

This filename is not enough to be unique across whole project (other cases have similar problem).
Use path with gapi entry (append path prefix) to avoid ambiguous problem in the future.

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

modules/gapi/samples/bind_before_serialization_example.cpp

modules/gapi/samples/custom_type_serialization.cpp

…i_serialization_docs

smirnov-alexey · 2021-07-06T15:26:41Z

@dmatveev please, take a look once again

dmatveev · 2021-07-07T18:19:16Z

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

 * @param bytes vector of bytes to deserialize GCompileArgs object from.
 * @return GCompileArgs object.
- * @see GCompileArgs S11N
+ * @see GCompileArgs cv::gapi::s11n::detail::S11N


hmm it is strange to see detail:: thing in the documentation -- is our overloadable S11N structure still there?

Yes, it's still there

smirnov-alexey · 2021-07-07T18:46:12Z

@alalek can we merge this, please?

…tion_docs G-API: add documentation on serialization functionality * Add documentation on serialization/deserialization * Add docs on bind() methods * Fix typo * Docs refactoring * Fix s11n docs * Fix deserialize() docs * Change deserialize docs * Fix warning * Address review comments * Fix sample * Fix warnings and errors * Fix docs warnings * Fix warnings * Address review comments * Add prefixes to snippets and fix indentation * Address review comments and move snippets to a single file

smirnov-alexey added 2 commits May 26, 2021 18:24

Add documentation on serialization/deserialization

b0636f4

Add docs on bind() methods

f38bdc0

smirnov-alexey added 6 commits May 26, 2021 19:26

Fix typo

9fac546

Docs refactoring

7ea301b

Fix s11n docs

aee49ad

Fix deserialize() docs

628b8dd

Change deserialize docs

2cdfa11

Fix warning

dfed9c3

smirnov-alexey commented Jun 3, 2021

View reviewed changes

dmatveev self-assigned this Jun 7, 2021

dmatveev added category: g-api / gapi category: documentation Documentation fix or update labels Jun 7, 2021

dmatveev added this to the 4.5.3 milestone Jun 7, 2021

dmatveev reviewed Jun 7, 2021

View reviewed changes

Address review comments

ef43aaa

smirnov-alexey added 5 commits June 21, 2021 18:02

Fix sample

ea43ff9

Merge branch 'master' of https://github.com/opencv/opencv into as/gap…

59c8006

…i_serialization_docs

Fix warnings and errors

bbfd7ed

Fix docs warnings

a09fc42

Fix warnings

9838a07

mpashchenkov reviewed Jun 22, 2021

View reviewed changes

TolyaTalamanov reviewed Jun 23, 2021

View reviewed changes

TolyaTalamanov self-requested a review June 23, 2021 11:07

TolyaTalamanov approved these changes Jun 23, 2021

View reviewed changes

mpashchenkov approved these changes Jun 23, 2021

View reviewed changes

Address review comments

78282bb

smirnov-alexey force-pushed the as/gapi_serialization_docs branch from 148f47d to 78282bb Compare June 23, 2021 12:23

alalek reviewed Jun 24, 2021

View reviewed changes

alalek reviewed Jun 25, 2021

View reviewed changes

Add prefixes to snippets and fix indentation

c9ad3d4

dmatveev reviewed Jun 28, 2021

View reviewed changes

smirnov-alexey added 2 commits July 6, 2021 16:29

Merge branch 'master' of https://github.com/opencv/opencv into as/gap…

4f24c11

…i_serialization_docs

Address review comments and move snippets to a single file

9114ee5

dmatveev approved these changes Jul 7, 2021

View reviewed changes

alalek merged commit 59ae0e0 into opencv:master Jul 7, 2021

alalek mentioned this pull request Oct 15, 2021

(5.x) Merge 4.x #20886

Merged

Uh oh!

Conversation

smirnov-alexey commented May 26, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Readiness Checklist

Uh oh!

smirnov-alexey commented May 26, 2021

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dmatveev left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

smirnov-alexey commented Jun 18, 2021

Uh oh!

mpashchenkov left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

smirnov-alexey commented Jun 23, 2021

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

smirnov-alexey commented Jul 6, 2021

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

smirnov-alexey commented Jul 7, 2021

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

smirnov-alexey commented May 26, 2021 •

edited

Loading