HackerOne users: Testing against this community violates our program's Terms of Service and will result in your bounty being denied.

Doxygen auto-generated documentation

JongosJongos
edited January 2012 in General Banter

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

  1. 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.

  2. 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.

  3. 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.

  4. Please excuse me for my bad English.

Comments

  • LincLinc Detroit Admin

    Nice work, @Jongos.

  • Awesame job.

  • UnderDogUnderDog MVP
    edited June 2012

    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?_

    There was an error rendering this rich post.

  • ToddTodd Chief Product Officer Vanilla Staff

    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.

  • @Todd

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

  • mcu_hqmcu_hq yippie ki-yay ✭✭✭
  • ToddTodd Chief Product Officer Vanilla Staff
    via Email
    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?
  • 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.

  • 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.

  • 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?

    There was an error rendering this rich post.

  • :) 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.

  • @UnderDog

    I apologize, Doxygen does support for Markdown.

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

  • @Todd

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

  • 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.

    There was an error rendering this rich post.

  • 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.

  • ToddTodd Chief Product Officer Vanilla Staff
    via Email
    Awesome. Thanks so much.
  • peregrineperegrine MVP
    edited November 2013

    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 :)

    I may not provide the completed solution you might desire, but I do try to provide honest suggestions to help you solve your issue.

  • peregrineperegrine MVP
    edited November 2013

    I may not provide the completed solution you might desire, but I do try to provide honest suggestions to help you solve your issue.

Sign In or Register to comment.