Doxygen anyone?

Hello, im using OpenFrameworks for about six months, and i have some suggestion’s .

First of all, you guys should use doxygen. Why? Because openframeworks IS A FRAMEWORK, and a framework should explain the most majority of their behavior/functions/classes inheritance and so on…

We have a major and outdated reference( openframeworks.cc/documentation ), but it’s not really detailed, and miss important notes and guides to you hack the code, like hack class diagram, related functions…

The second suggestion i have, is to make your svn’s more openly. I’m not talking about opening the password of svn for more hackers, and open your PATCH APPROVAL PROCESS! You know, the people just send a huge zip, with just 10 lines of code changed from the original of core. Why not use patch’s? Much more easy! But that’s not the point, the point is HOW DO WE KNOW THAT THIS FEATURE WILL ENTER THE NEXT OF VERSION? WHAT IS THE MAIN GUIDELINES OF THE DEVELOPERS? WHY MY PATCH WILL NOT ENTER THE OF CORE?

And this question has a specific answer. Bugtracking system. With bugtracking, we know what are the intentions to the next version of OF, we can also help you guys on this and that janitor tasks, and we can scream a lot about bugs!

That my main complaint, no organization of Openframeworks. It’s ok, it’s your guys shit, but it’s a mess. You can also use milestones, a wiki and so on, but i don’t think it’s really necessary at this point…

Regards.
Vitor Calejuri.

Hi Vitor

I can’t comment on the svn or bug tracking, but I’m in charge of the website and want to reassure you (and anyone else) that a new site is on the way.

The documentation will be up to date, have all the things you mention plus a lot more.

We didn’t want to use doxygen as a) it bloats the source code b) the look of the documentation generated wasn’t flexible enough for the system I wanted to create.

Chris

[quote author=“frangossauro”]Hello, im using OpenFrameworks for about six months, and i have some suggestion’s .

First of all, you guys should use doxygen. Why? Because openframeworks IS A FRAMEWORK, and a framework should explain the most majority of their behavior/functions/classes inheritance and so on…

We have a major and outdated reference( openframeworks.cc/documentation ), but it’s not really detailed, and miss important notes and guides to you hack the code, like hack class diagram, related functions…

The second suggestion i have, is to make your svn’s more openly. I’m not talking about opening the password of svn for more hackers, and open your PATCH APPROVAL PROCESS! You know, the people just send a huge zip, with just 10 lines of code changed from the original of core. Why not use patch’s? Much more easy! But that’s not the point, the point is HOW DO WE KNOW THAT THIS FEATURE WILL ENTER THE NEXT OF VERSION? WHAT IS THE MAIN GUIDELINES OF THE DEVELOPERS? WHY MY PATCH WILL NOT ENTER THE OF CORE?

And this question has a specific answer. Bugtracking system. With bugtracking, we know what are the intentions to the next version of OF, we can also help you guys on this and that janitor tasks, and we can scream a lot about bugs!

That my main complaint, no organization of Openframeworks. It’s ok, it’s your guys shit, but it’s a mess. You can also use milestones, a wiki and so on, but i don’t think it’s really necessary at this point…

Regards.
Vitor Calejuri.[/quote]

Hi Vitor,

Thanks for the feedback.
Most of your points are well made and actually are the direction we are heading in. We know the current state of things is a mess and we apologize for that. We are all juggling the OF project with our professional careers, so it has not always been easy to make the large structural changes needed to make the system cleaner, more transparent and less of a mess. But we are getting more help now and we are currently moving things towards a more organized OF.

These things include:

  1. A single OF package in svn (for all IDEs/OSs ) which will make updating from svn and making new releases a LOT easier.

  2. A new website with proper code and api documentation. This will include better instructions for keeping your OF up to date with svn.

  3. A proper bug tracking system. This has been more of a web issue than a deliberate decision - we used to use trac but it was just too prone to crashing. We are in sore need of a bug tracking system and this will come with the new site. Trust me its as painful for us as it is for you :smiley:

In regards to Doxygen and to expand on what Chris said, we all personally don’t like it. I find that it leads to poorly documentation / under documentation that is often too generic and impersonal to be of use. We like when you can have a paragraph of documentation when it is needed but with Doxygen you have a trade off between code legibility and comprehensive documentation. Also as we are a code framework for artists, it makes sense to present the api in a way that is easy and straightforward to understand, rather than the doxygen approach of showing how everything is connected to everything else which seems better suited for software engineers.

Thanks
Theo

openframeworks should use github. its that simple!

versioning, branching, issue-tracker, release-tagging(auto packageing), distributed development (easy overview, and rebase/merging), commit-comments/disscussion, forking and more

doxygen would become obsolute when openframeworks uses TDD or at least Unit-Test and Spec to proof the code and its behavior. these specs commonly generate your documentations!


svn is the wrong choice for an openly-developed framework like openframeworks, but these are only my thoughts…

Hey Lian,

Thanks for the advice - we are very interested in Git Hub, the project management tools, bug tracker etc look great.

If it can genuinely solve our headaches and consolidate our development then it could be a good option. I just don’t like that it is a hosted solution rather something we could have within as part of our own site.

But we will look into it seriously.

Thanks,
Theo

whats the problem with github hosting the master-branch? once you did a clone/checkout to your local-repository, you got everything anyways… plus, move the hosting to another site is just a simple a ‘pull origin github’ + ‘push origin my_new_hosting_site’

think of the social-coding part - thats is why people and huge projects moved to github beside other git-hosting sites.

// edit
for a oF package, submodules can be a good way to manage multiple libs/addons-repositories and provide a ‘virtual’ package which contains all deps and stuff needed in the final package… sort of *.debs are often used in debian-distros, where the ‘ruby’ package is only a virtual one which has deps (ie ruby18, ruby-dev, …) and install those aswell… on the ‘ruby’-package side, keeping up maintenance is very simple, you only need to change the version-string/hash of the depended package that was updated, nothing more. its like CVS/svn-externals but more enjoyable/maintainable :wink:

http://gitcasts.com/posts/git-submodules (15min submodule intro)
http://speirs.org/2009/05/11/understand-…-ubmodules/
http://daniel.collectiveidea.com/blog/2-…-submodules
http://git.or.cz/gitwiki/GitSubmoduleTutorial