Document public interface

[Sam Preston]

We need at least minimal doxygen documentation for all functions exported to python, since these are included in the python docstrings along with the corresponding function definitions.

[Caleb Rottman]

Can you explain exactly how to add documentation so that the comments export correctly to python? This might be good info to add to the wiki. I know currently we have a lot of undocumented functions where the help looks like this (pretty unhelpful):

Help on function SplatField in module PyCA.Core:

SplatField(*args)
    SplatField(Field3D a_o, Field3D a_i, Field3D h, StreamT stream = 0)
    SplatField(Field3D a_o, Field3D a_i, Field3D h)

    ================================
    Doxygen Documentation
    ================================
    void PyCA::Opers::SplatField(Field3D &a_o, const Field3D &a_i, const
    Field3D &h, StreamT stream=NULL)

[Sam Preston]

You just need to document the C++ header files with doxygen-style comments. There's lots of features you can put in there (you can find all about them in the doxygen documentation), but for the purposes of importing the documentation in to python you just need to put a comment before the corresponding function that starts with /** and ends with */, for example:

/**
 * takes some inputs and produces some outputs
 */
void MyFunc(...);