Ask Your Question
6

comments in OpenCV source code

asked 2012-09-04 16:42:52 -0500

iVlad gravatar image

updated 2012-09-04 16:45:41 -0500

It is not a secret that OpenCV source code is poorly commented. So if one wants to dive deep into the source and understand, modify or speed it up it is hard to do. I plan to create a wiki where I would start painstakingly add comments (marked in a special way to distinguish them from original ones) to the most widely used modules/functions (without modifying the original code or comments). My question is whether somebody else has undertaken a similar effort? If not, what is a best way to do this? I currently got a domain and a wiki software and plan to organize it in such a way that crowdsourcing is easy and possible wrongdoing is minimized.

My current problems is to how provide a right color scheme for C++ and what is the best form to prevent users from modifying or shifting around the original code or comments. Currently, I consider keeping new comments separately in some kind of xml file (internally) that can be fused with original code. A wiki user will see it (externally) as a fused version where original code/comments are unavailable for editing.

edit retag flag offensive close merge delete

Comments

that's goind to be hard. really hard. +1 anyway

yes123 gravatar imageyes123 ( 2012-09-04 18:12:23 -0500 )edit
4

Could you provide a particular example clarifying what you're going to do?

Point to some OpenCV function code and share what comments you'd like to add there.

Andrey Pavlenko gravatar imageAndrey Pavlenko ( 2012-09-05 06:50:45 -0500 )edit
1

here is a start: http://opencvcomment.com The files marked with red are in need of more comments

iVlad gravatar imageiVlad ( 2012-09-21 03:16:18 -0500 )edit

iVlad, are you going to merge your comments back to the OpenCV sources? If not, the whole project doesn't make much sense, because comment should be in the sources, right? If yes, who/when/how will merge newly added comments? I know the answer for the "who" part - OpenCV devs. But they accept only git patches or pull requests from the github. So, how often are you going to provide your patches with comments? How are you going to sync your wiki with changes in the OpenCV master?

Kirill Kornyakov gravatar imageKirill Kornyakov ( 2012-09-21 10:31:32 -0500 )edit

eventually I will do it. But I wanted to ask you, why are you concerned about merging? I would be concerned with commenting itself since it will take 99% of the overall work. You see, the difference between system guys and computer vision guys is that they really think differently.

iVlad gravatar imageiVlad ( 2012-09-22 00:54:06 -0500 )edit
1

You know, I really appreciate your effort. I think it would be very useful to clarify some parts of the OpenCV code. And I really want to see your comments merged back to the code base. I'm just afraid that another OpenCV revolution may come and your comments may become irrelevant. For instance, OpenCV 2.5 is going to introduce micromodules, where old elephants like highgui and imgrpoc are going to be split into 2-4 micromodules. So, without regular merges 1% of the overall work may grow into exhaustive copy-pasting. And this may kill the whole initiative...

Kirill Kornyakov gravatar imageKirill Kornyakov ( 2012-09-24 03:15:06 -0500 )edit

2 answers

Sort by ยป oldest newest most voted
4

answered 2012-09-11 08:33:39 -0500

Tom Anderson gravatar image

updated 2012-09-11 08:40:43 -0500

Further to Adi's answer, there is a github fork of OpenCV. You could simply fork it, add your comments to the code in your fork. When you found others who also wanted to help, they could fork your fork and push changes up to you, and it would be up to you to merge the changes into your fork.

This is the OpenCV github mirror. https://github.com/itseez/opencv

The OpenCV maintainers say that they will eventually respond to pull changes from GitHub, stating, "We are going to organize the process of adopting pull requests a bit later."

The advantage of Github over a Wiki is that the code is readily downloaded in runnable form, and secondly you can easily keep updated with changes over multiple computers. The disadvantage would be that you would no longer be creating your own site, you would be beholden to the Github overlords, but forks on GitHub are free.

edit flag offensive delete link more

Comments

Yes, we are accepting pull requests regularly, so you can use this mechanism.

AlexanderShishkov gravatar imageAlexanderShishkov ( 2012-09-11 08:37:11 -0500 )edit

Ooh, time to update. That quote "We are going to organize the process of adopting pull requests a bit later." is from: http://code.opencv.org/projects/opencv/wiki

Tom Anderson gravatar imageTom Anderson ( 2012-09-11 08:41:37 -0500 )edit
2

+100 for pull requests instead of separate wiki, xml and other scary things...

Kirill Kornyakov gravatar imageKirill Kornyakov ( 2012-09-12 10:55:23 -0500 )edit
0

answered 2012-09-05 12:34:34 -0500

Adi gravatar image

Git will easily show you the diff between any edits and the original committed version.
Any good diff tool that understands C/C++ (or any other language) can differentiate between code edits and comments.

edit flag offensive delete link more

Comments

wiki has versioning and diff functionality. it is easy to use while git is not always intuitive. Anyway, how many people did bother to add comments or do something like this with or without git?

iVlad gravatar imageiVlad ( 2012-09-21 03:19:01 -0500 )edit
Login/Signup to Answer

Question Tools

Stats

Asked: 2012-09-04 16:42:52 -0500

Seen: 627 times

Last updated: Sep 11 '12