Doxygen auto-generated documentation

Jongos

Hi...

I'm new to OOP, and spent days trying to understand Garden, tried a lot of things to do so (like using 3 different IDE to help visualize the relations between classes, eg. hierarchy/usages/referrence/etc.).

Reading vanillaforums.org/docs and then trying to figure out the class hierarchies and later finding what file has what class/methods is quite frustrating/hampering.

Finally I've tried Doxygen with Vanilla/Garden (to accompany the great tutorials by @Mark) and found that it helps a great deal.

Here's the docs...

Mediafire - html.rar - 14.59 MB

Notes :

1. For simplicity and to make only the relevant classes/functions are documented some folders were excluded.

/library/vendors

/plugins

/applications/skeleton

/themes/EmbedFriendly

/themes/mobile

/locales

2. Since the classes/methods/functions are not well tagged/commented, I've included the source code into the documentation so readers could make their own deduction of the functionality of the classes/methods/functions without having to fireup an editor/IDE and lose focus.

3. Many functions, well most of the functions went undetected by both Doxygen & PhpDocumentor because it was enveloped by if (!function_exist(function_name)){...} , so for the purpose of documenting it i have manually removed those. Maybe it's a bad idea, i don't know. Just think you guys need to know.

4. It made use the GraphViz Dot generated charts, super awesome, with UML like charts interconnected among superclasses and subclasses... and also which class calls what other class.

5. Please excuse me for my bad English.

Linc

Nice work, @Jongos.

evolucja

Awesame job.

UnderDog

Ok, I'm gonna break my own rule here :-P (bumping topics older than 3 months is frowned upon)
First of all thanks for generating this documentation @Jongos ! Now we need to figure out what the Vanilla guys want. We need to be generating this documentation often so we need all the functions to be documented somehow.

_Any advice on editing the Vanilla source solely for documentation purposes?_

Todd

Give us a quick rundown on doxygen and we'll give it a real look. I'd love to have auto-generated documentation pushed to the site.

Jongos

@Todd

Sorry, I don't understand what you mean with rundown... Love to help.

mcu_hq

this has been done already:

http://fossies.org/dox/Vanilla_2.0.17.10/annotated.html

Todd

Like do I just download the app and point it at our source code or are
there any gotchas I need to be aware of?

Jongos

UnderDog said:
Ok, I'm gonna break my own rule here :-P (bumping topics older than 3 months is frowned upon)
First of all thanks for generating this documentation @Jongos ! Now we need to figure out what the Vanilla guys want. We need to be generating this documentation often so we need all the functions to be documented somehow.

_Any advice on editing the Vanilla source solely for documentation purposes?_

What i put on the starter post up there says much about what is needed.

The big ones would be :

1. have a more elaborate phpdoc style of comment block (eg. @param, etc.)
2. find a way to have Doxygen detect functions inside if (!function_exist(function_name)){...}

I'm not sure I still have the Doxygen settings... I will put it up when I have time.

Jongos

Todd said:
Like do I just download the app and point it at our source code or are
there any gotchas I need to be aware of?

refer to first post.

and if you want the fancy hierarchy charts you need to install GraphViz Dot on your computer and point Doxygen to the executables.

UnderDog

Jongos said:
2. find a way to have Doxygen detect functions inside if (!function_exist(function_name)){...}

Yep, that's a big one... We can get around the @param etc things, the documentation will still get generated, but not around the if (!function_exist( part...

I'm looking into other questions (on stackoverflow) that were asked about auto-documentation.

My biggest thing is to generate Markdown (?) instead of pure HTML?

Jongos

I can't help you with that one.

You might need to hack Doxygen code for that, and compile it yourself.

Also relationship of some classes got wrongly mapped. Like, some classes are not mapped as a child of some other class. For my purpose, it's not a problem. I only want a good picture of the relationship between the classes (which are the senior-most classes where majority other inherit from, etc.) But there's only 2 or 3 cases like this.

Jongos

@UnderDog

I apologize, Doxygen does support for Markdown.

http://www.stack.nl/~dimitri/doxygen/markdown.html

UnderDog

I've found a couple of links with nice articles:

• http://www.codeproject.com/Articles/3528/10-Minutes-to-document-your-code
• http://stackoverflow.com/questions/101146/anything-better-than-phpdoc-out-there

Jongos

@Todd

Give me some time... When I have time I'll play with Doxygen and will give settings and maybe some write ups.

UnderDog

May I suggest to take an extra look at phpdocumentor too, please? There's phpdoc 2 out (recently). Let's see which one is the most appropriate / adjustable.

Jongos

UnderDog said:
May I suggest to take an extra look at phpdocumentor too, please? There's phpdoc 2 out (recently). Let's see which one is the most appropriate / adjustable.

Looks good. Worth a try. Thought it's dead for good.

For Doxygen, i think i found the solution for the if (!function_exist(function_name)){...} problem : http://www.stack.nl/~dimitri/doxygen/commands.html#cmdcond

enclosing the if (!function_exist()) and it's closing bracket with @cond/@endcond might solve it. Maybe. Haven't test it yet.

Todd

Awesome. Thanks so much.

peregrine

I just downloaded doxygen locally. pretty nice to have it on local machine if you've got a chance to play with it.

http://www.stack.nl/~dimitri/doxygen/download.html

e.g. discussion model 2.1b2 in a nutshell

hbf

http://vanillawiki.homebrewforums.net/CodeDocs/V2.0.18.8/html/

peregrine

@hbf said:
http://vanillawiki.homebrewforums.net/CodeDocs/V2.0.18.8/html/

quick follow-thru hbf

http://vanillawiki.homebrewforums.net/CodeDocs/2.1b/html/