Updating the documentation


#1

I’d like to update the documentation a bit, especially by adding some example code to the more basic functions as I really missed those myself starting out with OF.
But before I start making changes I want to check how the docs are created at the moment.

For instance, the drawCircle docs only show the drawCircle(float x, float y, float z, float radius) method, not the other three options:

The documentation page has a “Edit class” link that will take you to Github where you can edit a markdown file (documentation/gl/ofGLRenderer.markdown in this case) and where the other options can be added, but I think I remember reading the documention is (in part) autogenerated? That would mean the other versions should have been included already.

Can someone shine some light on this, and possible point out any caveats concerning updating the documentation?

edit:
And of course, if there are any things that you already know need updating.


#2

Thanks so much, contributions to the docs are always welcomed and really needed.

I’m seeing 2 versions of ofDrawCircle right now:

http://openframeworks.cc/documentation/graphics/ofGraphics/#!show_ofDrawCircle

They are different from the code in master cause the docs belong to the current stable version of OF so the glm::vec2 and glm::vec3 versions are not there yet.

If you want to add code examples, images or in general longer explanations the markdown file you point out is the right place to do so but only add coments below the _description tag using markdown syntax don’t add any function since the functions are autogenerated from the code with every release.

For long explanations with examples or images also consider documenting the file or class, in this case ofGraphics:

http://openframeworks.cc/documentation/graphics/ofGraphics/

or even the module docs, in this case graphics:

http://openframeworks.cc/documentation/graphics/

If you want to add sort explanations of what each method does then you can add them in the code itself too using doxygen syntax, in this case ofDrawCircle already has some code comments with a sort example that comes from:

that should be more or less the max size of a code comment anything longer than that, with more complex examples or images should go into the markdown files


#3

They are different from the code in master cause the docs belong to the
current stable version of OF so the glm::vec2 and glm::vec3 versions are
not there yet.

It might make sense to change the docs in a temporary branch first and merge them when the new OF is released to prevent confusion with docs that are ahead of the current release.

I do find it a bit confusing to have documentation both in the code and in the markdown file. Wouldn’t it be better to put all of the docs into the markdown (as both short and long comments fit in there)? I do get that it’s sometimes nice to directly see some info while browsing the code, but things like “not too long” seem a bit arbitrary.
Having everything in one place sounds like the most organized solution. Of course, if there is a special reason for using this system, I’ll work with it. Just checking :wink:


#4

yes that could make sense we want to have release and pre-release docs at some point so once that’s working you should be able to contribute docs for any of the versions

and yes having docs in both places can be confusing and it mostly comes from different opinions in the OF community where some people prefer to fill documentation in code comments and others think that it’s more accessible to use markdown files so anyone can edit them without having to edit the code directly. in the end we arrived to this kind of compromise where short docs go in the comments which also helps developers documenting things as they code and long more explanatory docs go in markdown so anyone can contribute longer explanations, examples images… in a simpler way.

In the end when the docs are generated for every release both things get merged in the markdown so both versions are available through the web page and if some comment docs and markdown docs are too similar only one of the two versions is shown


#5

Hi @javl, I wanted to do exactly the same, and had the same questions. Great to read @arturo’s explanation.

I thought it would be nice to write a program that generates images that are used for the documentation. I started one here: ofSetBoxResolution() has no effect

It also could serve as a way to detect changes in functionality, in case the resulting graphics are somehow wrong.

Maybe to avoid doing repeated work there could be a wiki page for the documentation effort, with a list of under-documented functions, and who will take care of them. Before working on something, we could check if someone is already doing that in that wiki page. Or is there another way of coordinating this?