Javadoc documentation imported from C++ about opencv HOT 8 CLOSED

JavaDocs are bundled with the Maven artifacts. Is there something specific that is missing?

from opencv.

Yes, the documentation itself is missing. Javadoc works — it just doesn't contain any documentation that C++ version of OpenCV have for its classes and methods.

For example Javadoc:

    //
    // C++:   CascadeClassifier(String filename)
    //

    //javadoc: CascadeClassifier::CascadeClassifier(filename)
    public   CascadeClassifier(String filename)
    {
        
        nativeObj = CascadeClassifier_0(filename);
        
        return;
    }

C++ version:

CascadeClassifier::CascadeClassifier
Loads a classifier from a file.

C++: CascadeClassifier::CascadeClassifier(const String& filename)
Python: cv2.CascadeClassifier([filename]) → <CascadeClassifier object>
Parameters:	filename – Name of the file from which the classifier is loaded.

from opencv.

We just bundle the JavaDocs that are created by the OpenCV build process. In the OpenCV build there is a step that examines the C++ and generates Java files from it. If I remember correctly, this generator will only pull in the docs that are specifically marked for JavaDoc. JavaCV effectively does the same thing but they seem to do it for all the docs.

So, if we want to do this we'd need to either modify the OpenCV generator ( https://github.com/opencv/opencv/blob/master/modules/java/generator/gen_java.py ), run something after the fact to build the documentation and insert it into the Java files or maybe run something beforehand to update the C++ files with the correct // javadoc comments.

It's going to be a fairly difficult task, but if someone is up to it I will be more than happy to accept a pull request.

from opencv.

Actually, it looks like something might have changed from 2.4 to 3.2.

Bundled docs from 2.4.13:

Bundled docs from 3.2:

For anyone interested in digging into this, I would look at:

• Do the C++ files still contain the //javadoc tags?
• Does the gen_java.py script still look for them and produce the right docs?
• Are the docs getting dropped somewhere between the OpenCV build and the bundle build?

from opencv.

Looks like OpenCV 3 switched to Doxygen documentation and I suspect the Java generator was never updated to use it. http://docs.opencv.org/trunk/d4/db1/tutorial_documentation.html

Example of difference in docs in the source code from 2.4 to 3.2:

2.4:https://github.com/opencv/opencv/blob/2.4/modules/imgproc/include/opencv2/imgproc/imgproc.hpp#L624

3.2: https://github.com/opencv/opencv/blob/master/modules/imgproc/include/opencv2/imgproc.hpp#L2570

The upside is that if all the docs are in Doxygen format now they should be much easier to deal with. But it's still going to require changes to the OpenCV gen_java.py to get them into the source files so they can be indexed by JavaDoc.

from opencv.

Okay, looks like this is an OpenCV 3.2 issue: opencv/opencv#8011

from opencv.

And here is the real issue: opencv/opencv#4286

From that issue: "After moving to doxygen, documentation for python and java is not generated anymore. This process should be reworked from scratch."

So it looks like this is going to take someone working with OpenCV to get this rewritten.

from opencv.

Closing this as won't fix. Maintaining this distribution is already incredibly difficult and time consuming. I'm not going add more complexity to it. If OpenCV ever fixes this issue the documentation will be included automatically. So, until then...

from opencv.