Τρίτη, 18 Δεκεμβρίου 2012

How to set up Doxygen for use in your Xcode Project



here is a great tutorial on the apple developer site with detail surrounding this process: 

http://developer.apple.com/tools/creatingdocsetswithdoxygen.html. However, I will try to add my own two cents to make the process go more smoothly and quicker for you!
Steps
1. Download the latest version of Doxygen here: http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc
2. Drag and Drop Doxygen.app to your Applications folder to install Doxygen.
3. To create better looking documentation, download and install GraphViz here: http://www.ryandesign.com/graphviz/
  • The following bullets may not be needed (it wasn't for me), but just in case, here you are some settings you may need to adjust within Doxygen.
  • The installer will install dot in /usr/local/graphviz-x.y/bin/dot
  • To use dot from within doxygen, set HAVE_DOT to YES and DOT_PATH to /usr/local/graphviz-x.y/bin
    (where x.y is the version of graphviz you installed, e.g. 2.14).
4. Open and configure Doxygen.
  • There are essentially two views in Doxygen where you can edit your configuration files: Wizard and Expert. When you open Doxygen, it will open to the Wizard view. Some settings will need to be changed in the Expert view. If you open your Expert view window and there is nothing there, fear not...just look for the little grey dot on the right of the screen and pull it over to the left. This pesky problem took me quite some time to figure out. You can then click "next" to navigate through the expert view.
  • There are only a few changes you need to make to the configuration file.
    1. Set the working directory, project name, source code directory, etc... Basically, fill out the wizard project form.
    2. Go into the Expert view and scroll through until you see the HTML editing screen.
    • In this section, you will see GENERATE_DOCSET. Check the box.
    • Fill in a DOCSET_BUNDLE_ID (something like com.RonJeremy.MyProject). This will be used by Xcode to create a docset viewable inside Xcode.
  • Save your configuration file and run Doxygen to confirm that the documentation was created. You should be able to click "Show HTML Output" to confirm.
5. Follow the remaining instructions from the apple developer website: http://developer.apple.com/tools/creatingdocsetswithdoxygen.html. They are very straightforward, however, I ran into two issues:
  1. The only issue I ran into was when I first tried to view my docset. In Xcode, if you navigate to Help...Documentation, you should see a 'root' in the top left (see figure 1). If you don't, you must open the docset in your doxygen project root/html folder. This docset has the name you specified in your configuration (com.RonJeremy.MyProject).
  2. After running my Xcode build, I noticed the documentation was not being updated. To fix this, I had to go into my Xcode project folder and locate the file named: doxygen.config. In this file, I found that GENERATE_DOCSET was set to NO. Simply changing this to YES resulted in the correct behavior.
Once the above steps are complete, you should see some auto-generated documentation:



Generate documentation from source code


Generate documentation from source code

Doxygen is a documentation system for C++, C, Java, Objective-C, Python, IDL (Corba and Microsoft flavors), Fortran, VHDL, PHP, C#, and to some extent D.
It can help you in three ways:
  1. It can generate an on-line documentation browser (in HTML) and/or an off-line reference manual (in $\mbox{\LaTeX}$) from a set of documented source files. There is also support for generating output in RTF (MS-Word), PostScript, hyperlinked PDF, compressed HTML, and Unix man pages. The documentation is extracted directly from the sources, which makes it much easier to keep the documentation consistent with the source code.
  2. You can configure doxygen to extract the code structure from undocumented source files. This is very useful to quickly find your way in large source distributions. You can also visualize the relations between the various elements by means of include dependency graphs, inheritance diagrams, and collaboration diagrams, which are all generated automatically.
  3. You can also use doxygen for creating normal documentation (as I did for this manual).
Doxygen is developed under Linux and Mac OS X, but is set-up to be highly portable. As a result, it runs on most other Unix flavors as well. Furthermore, executables for Windows are available.