doxygen code example for team

[GoogleCodeExporter]

Joe is going to send a code example to everyone to set a basic guideline for 
collaborating on doxygen.

Original issue reported on code.google.com by ard...@gmail.com on 17 Nov 2010 at 12:21

[GoogleCodeExporter]

updating metadata

Original comment by ard...@gmail.com on 17 Nov 2010 at 12:21

[GoogleCodeExporter]

I was going to attach the Doxygen-generated docs as a tarball to this bug, but 
the file is 217 megabytes, which exceeds the 10MB limit ;)

So, instead, I've attached the Doxygen config file I used to generate them.  
The command I ran was:

doxygen Doxyfile

Where Doxygen looks for source to document, and where it puts the generated 
docs, is controlled by that file.  So, you'll want to edit to to suit your 
needs (searching it for the string "jardent" should be good enough).

As an example of how to use Doxygen, look at the file 
lib/Alembic/Abc/OSchema.h, starting on line 46.  You can see the basic idea is 
to simply make your comments like:

//! With properties, specific flavors of properties are expressed via the
//! TypedScalarProperty and the TypedArrayProperty. Compound Properties
//! are more complex, and the specific flavors require a more complex
//! treatment - That's what Schemas are. The CompoundProperty equivalent
//! of a TypedArrayProperty or a TypedScalarProperty.

that is to say, '//! <text goes here>'.

I like this writing sample because it provides a high-level overview of what's 
going on conceptually, and ties it in with other concepts in the system.  Of 
course, most of the code doesn't warrant that sort of writing, but when it 
does, comments like that are great.

Original comment by ard...@gmail.com on 17 Nov 2010 at 12:21

[GoogleCodeExporter]

I updated some of the settings in Joe's example to make sure a few out of place 
symbols don't make it into the documentation.  (boost::adder, IllustrationOnly, 
some python stuff)

It also is only looking at the headers in AbcCoreAbstract, AbcCoreHDF5, 
AbcCoreHDF5, AbcGeom, MD5Hash, and Util.  This greatly reduced the time it took 
to create the docs and helped keep out some unwanted riff-raff.

I also updated the default branch and removed some tags that either created 
weird looking documentation (the two macros using \example) or doxygen 
complained about (\ref usage when unnecessary)

The docs are still big though 120 MB.

Original comment by ard...@gmail.com on 17 Nov 2010 at 12:21