[Kyle's list] 5 - Documentation

_[as someone suggested this, I will open a thread for the main points Kyle brought up in this 007 megamail. First post is his original point. I could use some help with people adding the main points of what has been discussed since then.]
_

in my opinion, examples + documentation should be at the top of the
‘priorities’ list right now

arturo told me that he tried exporting doxygen documentation at one
point. i’d really like to see what that looks like. i don’t know if
it’s the solution, but there’s definitely something wrong with the way
things are now:

  • the website has instructions both for setting up IDEs, and a
    reference for core functionality
  • the readme.platform that comes with the release has some
    instructions for setting up an IDE, and a couple comments about minor
    idiosyncracies. it also refers you to the website.
  • there is no core documentation distributed with the release besides
    the readme and examples
  • the header files are littered with things like:

// this does a crop from another image.
// NOTE: this will reallocate memory if the image types are
different, or if the w & h do not
// equal this images w & h

which is super important for people to know… but maybe in the wrong
place. and, personally, i just get really weirded out by the
inconsistency. the fact that some comments are aligned, some aren’t,
sometimes you see “NOTE:”, sometimes it’s in all caps, sometimes it
has a link to a url that is relevant, sometimes it is just a
high-level explanation that a few people understand, sometimes it’s in
the .cpp sometimes .h… etc.

i think we’re kind of at a turning point. OF was originally about
looking at the source to understand what is going on, and finding
little comments scattered throughout. it was meant to be an
introduction to C++ and to OF simultaneously. but now i think we’ve
worked away from that a bit, and need to embrace it. if you look for
the implementation of ofTranslate, you’re just going to see something
like curRenderer->translate(). it doesn’t make sense to write:

// this calls the current renderer, which might be opengl or cairo,
and tells it to translate

but that kind of documentation definitely has to show up somewhere! i
think the right way to go is to have really badass html documentation
that can live on the site and be distributed with the release. it
should have some tutorials (not examples, but explanations of the “how
and why”) and a reference (like processing’s, or the current OF
reference).

also, big shoutout to roxlu for his presentations. this exists
somewhere on the border between tutorials and reference, and has a ton
of super-essential information:
http://www.roxlu.com/blog/entry/145/openframeworks-007-presentations/page/

doxygen seems to be a consensus as to how to generate documentation. ben and philip alread whipped up and awesome first test:
http://ofxfenster.undef.ch/doc/
including a github repo: https://github.com/benben/ofDoc

One question has turned up (i think): How can we automate this as much as possible?

We’ve been talking about that here: http://forum.openframeworks.cc/t/of-documentation/5566/0

Should we merge posts?

@arturo:

how are the docs for the website currently generated? so maybe we can hack up this a bit to integrate that in the doxygen stuff

seth: I don’t think we should merge, a link is sufficient, there’s not too much essential info in that thread.

benben, underdoeg: could you also include the core-addons in the doxygen documentation? and i think it’s been mentioned on the list, that it would be nice if the header was smaller, not eating so much screen space…

Yeah, we can and will definitely do that. But I think before we start tuning the overall layout, we really have to think about the “beginners” part of the documentation. Does anybody know how it is currently generated? Could we maybe change the existing system so it generates doxygen command like the ones I used already instead of html? How hard is it to document new classes like ofMesh, etc… ?

And is anybody / how many already using our doxygen? Did you find it usefull, what could we do to improve?

I used it a couple times. Not very much, though, so I still find the structure a bit strange (sorry don’t know how to explain). Which is why I wanted to have the addons, I will be playing with oxfOsc quite a bit for a while, though about learning/checking with your new docs…

Just added the core addons as well. Had to do it manually, something like addons/*/src didn’t seem to work. So it’s possible that I forgot one… But ofxOsc is there :wink:

I also removed the header for now. As it gives more space, I still think the logo should be in there somewhere but it’s not that urgent, I guess.

thanks :slight_smile: