Opencv: Documentation improvement plan

[sturkmen72]

i have a request and a suggestion about Documentation improvement plan

i already made some contributions related to documentation and i want to keep working on it. I want to work according a right plan so if some tasks that users can do are identified clearly i will choose a task and work on it. after completing a task choose another and so on.

my suggestion is gathering feedbacks from users in documentation pages

for example see msdn.microsoft.com
there is "Is this page helpful? Yes No"

[catree]

I have some suggestions:

• progressively start to merge the contents of the Python tutorials into the C++ tutorials:

  • for instance some of the Python tutorials in the Feature Detection and Description chapter are not present in the C++ tutorial (e.g. this tutorial)
  • when a tutorial is available in C++ and in Python (e.g. Harris corner detector, C++, Harris Corner Detection, Python), start to merge the non redundant information (this image (from Matching with Invariant Features, Darya Frolova, Denis Simakov, The Weizmann Institute of Science, March 2004) is helpful to understand the concept)
  • the end goal would be to have only one entry point for the tutorials with the possibility to switch between the different programming languages as in this tutorial

• similarly to the Python documentation, be able to browse directly the Github source code of a function from the OpenCV documentation

  • for instance for Canny documentation, in Python scikit-image there is a link to the source code
  • browsing a specific version of the documentation should lead to the correct tagged source code
  • not sure if it is feasible with Doxygen? There is something called SOURCE_BROWSER but I don't know if it completely appropriate
  • offline documentation should also have a link to the source code somehow?

The first point should be relatively easy as it should be mostly some copy-pasting. The hard part should be to provide the code in C++, Java and in Python but it can be done progressively.

The second point is more a personal request as I have sometimes some difficulties to locate the source code of a function and the Github search option returns too many results.

[catree]

I have tried to improve the documentation (list of PRs) by adding Java and Python code to some C++ tutorials.
Here some suggestions / guidelines I propose to follow. Discussion and proposition are welcome.

Write code that follows good practices

• C++:
  
  
  
  • drop parameters with already good default values, for example imread(filename, IMREAD_COLOR) should be replaced by imread(filename) in my opinion
  
  
  • avoid using pointers, global variables if not needed
  
  
• Java:
  
  
  
  • try to follow naming and coding convention specific to Java (e.g. CamelCase naming)
  
  
  • formatting can be easily and automatically done using for instance the Eclipse IDE
  
  
• Python
  
  
  
  • try to write pythonic code (e.g. index slicing, itertools?)
  
  
  • for efficiency, try to use directly Numpy function instead of rewrite it using for loops
  
  
  • try to write Python 2 / 3 compatible code, see http://python-future.org/
  
  
• in all case, try to declare variables the closest to their usage. It helps the comprehension of the program.
• try to use CommandLineParser in C++ and argparse in Python for command lines option

Tutorial content

• try to write in a way consistent with the other tutorials
• a good outline for a tutorial should be in my opinion: (introduction +) theory / code / explanation / references (if any)
• in my opinion, explanation of the code is not necessary since the tutorial code should be made self-explanatory
• I would favor first a good tutorial code (especially in Java and Python where there are less examples), then the theory if the topic needs it
• tutorial code should be embedded with @snippet doxygen command instead of @code command. This allows the code to be automatically verified for syntax error and to be run easily.

Suggestions / improvements

• I have noticed that somehow with Numpy documentation the first referenced link by google is always from the latest documentation version
• I wonder if something could be done, maybe in the search engine optimization parameters? This would avoid user to look at outdated documentation, since I regularly see people linking to the outdated 3.0-beta documentation.
• I think an improvement could be to add accepted mat type in function inputs, especially for the imgproc module?
• also, it would be great to have a note if a function is optimized using OpenCL or IPP
• normalization / consistency in the path of the tutorial code. Currently, I sometimes find quite difficult to find the corresponding code for a given tutorial (e.g. some imgproc tutorials are in ImgTrans directory).

[catree]

Related issue to close or redirect the obsolete and no more maintained Python tutorial website.

---

At the same time, mention about 2.4 OpenCV documentation being obsolete should be added. Here some examples for other libraries:

• http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.dui0348c/index.html

• https://docs.scipy.org/doc/numpy/reference/generated/numpy.eye.html

2.4 OpenCV branch still exist and the corresponding 2.4 documentation is still relevant. But most of the time, people that arrive on 2.4 doc are newcomers that just google something about OpenCV.

---

For tutorials improvement, a good thing would be to add references to the corresponding chapters of the Szeliski book.

Good theory with practical examples would be the best for the OpenCV tutorials. For instance, I have found this course.

Also, there are C++, Java and Python code in lot of OpenCV tutorials. Something like Python notebook could also be explored for interactive code.