1. Code Documentation & Doxygen Issa Mahasneh servit Open Source Solutions www.servit.ch

2. A Short Introduction to Technical Documentation ● Every product and project under development should be documented. ● Documentation may describe: ● Functionality (what the system does). ● Architecture (how the system is implemented).

3. Document Types in Development ● System Requirements. ● System Design. ● System Architecture.

4. Code Documentation - Why? ● It acts as a specification of behavior for other engineers. Without documentation, they are forced to get the information they need by making dangerous assumptions, scrutinizing the implementation, or interrogating the author. ● There is a great deal of information about code behavior that simply cannot be expressed in source code, but requires the power and flexibility of natural language to state. ● It is an irreplaceable necessity, as well as an important discipline to increase development efficiency and quality.

5. Code Documentation – Other Reasons! ● Your company requires some documentation. ● You're not convinced you understand all of your code after not looking at it for half a year. ● Your co-workers pester you with "how do I do this" questions about your tool library. ● You plan to retire or move on, and don't want your precious code to end up in the garbage, pillaged and rewritten by someone you don't even know, just because he doesn't take the time for it. ● You feel better

6. Code Documentation ● Developers should document their code: 1.Describe the intended operation. 2.Describe how an operation is managed. 3.Give additional relevant information.

7. Paradigms ● Literate Programming ● Elucidative Programming

8. Automated Documentation ● If you write your code using a specific standard, you will be able to obtain a full reference documentation using some automated tools. ● One of these tools is Doxygen.

9. Automated Documentation - Why? ● Documentation is up-to-date ● Reuse of your own comments ● Automatic formatting, and crosslinking. ● In-code comments carry important meta information.

10. Doxygen ● Doxygen is a documentation generator for C++, C, Java, Objective-C, Python, IDL, Fortran, VHDL, PHP, C#, and to some extent D. ● It runs on most Unix-like systems, including Mac OS X, as well as on Windows. ● The first version of Doxygen borrowed some code of an old version of DOC++; later, the Doxygen code was rewritten by Dimitri van Heesch.

11. Why Doxygen? ● It's gratis. ● OpenSource with installer. ● Configurable.

12. Doxygen - Diagrams ● Caller and callee graphs ● Dependency graphs ● Inheritance diagrams ● Collaboration diagrams

13. Doxygen – Other Info ● First published in 1997. ● Latest stable version: 1.5.7.1

14. Writing Comments ● <?php ● // $Id: panels_page.module,v 1.36.2.10 2008/12/29 04:09:38 sdboyer Exp $ ● /** ● * @file panels_page.module ● * ● * This module is the primary implementation pf the Panels API. It provides ● * Panel pages that are used to create full page layouts. It utilizes numerous ● *.inc files for various segments of its functionality. These includes are ● * lazy-loaded (some through the menu system, some internally) in order to keep ● * code weight to an absolute minimum. ● */ ● /** ● * Indicates that the item utilizes a dynamic path - that is, it has a ● * wildcard (%) in its path. ● */ ● define('PANELS_IS_DYNAMIC', 1); ● /** ● * Implementation of hook_help(). ● */ ● function panels_page_help($path, $arg) { ● $output = NULL; ● switch ($path) { ● case 'admin/panels/panel-page': ● >'; ● break; ● case 'admin/panels/panel-page/add': ● $output = ' '; ● $output.= t('Choose a layout for your new page from the list below.'); ● $output.= ' '; ● break; ● } ● return $output; ● }

15. First Step ● Download it from: http://www.stack.nl/~dimitri/doxygen/download.ht ml#latestsrc

16. Running ● A GUI application is avaialble for Windows ● Start -> Programs -> Doxygen -> DoxygenGUI

26. Thank You! ● Questions ???