Document the rest of the files in src/core.

4 files changed, 286 insertions, 22 deletions

diff --git a/src/core/object.h b/src/core/object.h
index 3d408dc..dfc0337 100644
--- a/src/core/object.h
+++ b/src/core/object.h
@@ -25,6 +25,11 @@
  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
+/**
+ * \file object.h
+ * \brief Object tree
+ */
+
 #ifndef __REFCOUNTED_H__
 #define __REFCOUNTED_H__
 
@@ -33,31 +38,86 @@
 namespace Coal
 {
 
+/**
+ * \brief Base class of all the Clover objects
+ * 
+ * This class implements functions needed by all the Clover objects, like
+ * reference counting, the object tree (parents/children), etc.
+ * 
+ * It also uses a special list of known objects, used to check that a pointer
+ * passed by the user to an OpenCL function actually is an object of the correct
+ * type. See \c isA().
+ */
 class Object
 {
     public:
+        /**
+         * \brief Type of object the inherited class actually is
+         */
         enum Type
         {
-            T_Device,
-            T_CommandQueue,
-            T_Event,
-            T_Context,
-            T_Kernel,
-            T_MemObject,
-            T_Program,
-            T_Sampler
+            T_Device,       /*!< \brief \c Coal::DeviceInterface */
+            T_CommandQueue, /*!< \brief \c Coal::CommandQueue */
+            T_Event,        /*!< \brief \c Coal::Event */
+            T_Context,      /*!< \brief \c Coal::Context */
+            T_Kernel,       /*!< \brief \c Coal::Kernel */
+            T_MemObject,    /*!< \brief \c Coal::MemObject */
+            T_Program,      /*!< \brief \c Coal::Program */
+            T_Sampler       /*!< \brief \c Coal::Sampler */
         };
 
+        /**
+         * \brief Constructor
+         * \param type type of the child class calling this constructor
+         * \param parent parent object
+         */
         Object(Type type, Object *parent = 0);
         virtual ~Object();
 
+        /**
+         * \brief Increments the reference counter
+         */
         void reference();
+        
+        /**
+         * \brief Decrements the reference counter
+         * \return true if the reference counter has reached 0
+         */
         bool dereference();
+        
+        /**
+         * \brief Reference counter
+         * \return the number of references of this class currently in use
+         */
         unsigned int references() const;
+        
+        /**
+         * \brief Set if the parent object has to be deleted if its reference count reaches 0
+         * 
+         * The destructor of \c Coal::Object dereferences its parent object.
+         * This is done in order to correctly free objects when no object has
+         * a reference to it anymore.
+         * 
+         * Some objects such as \c Coal::CommandQueue need to do some operations
+         * before being deleted. This function tells \c Coal::Object to
+         * dereference its parent object, but not to call \b delete on it.
+         *
+         * \param release true to have \b delete called on the parent object
+         *        when its reference count reaches 0, false to keep it
+         */
         void setReleaseParent(bool release);
 
-        Object *parent() const;
-        Type type() const;
+        Object *parent() const;    /*!< \brief Parent object */
+        Type type() const;         /*!< \brief Type */
+
+        /**
+         * \brief Returns whether this object is an instance of \p type
+         * \note This function begins with a NULL-check on the \c this pointer,
+         *       so it's safe to use even when \c this is not guaranteed not to
+         *       be NULL.
+         * \param type type this object must have for the check to pass
+         * \return true if this object exists and has the correct type
+         */
         bool isA(Type type) const;
 
     private:
@@ -70,4 +130,4 @@ class Object
 
 }
 
-#endif
\ No newline at end of file
+#endif
diff --git a/src/core/program.h b/src/core/program.h
index 843fb82..ba39c37 100644
--- a/src/core/program.h
+++ b/src/core/program.h
@@ -25,6 +25,11 @@
  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
+/**
+ * \file core/program.h
+ * \brief Program
+ */
+
 #ifndef __PROGRAM_H__
 #define __PROGRAM_H__
 
@@ -50,49 +55,146 @@ class DeviceInterface;
 class DeviceProgram;
 class Kernel;
 
+/**
+ * \brief Program object
+ * 
+ * This class compiles and links a source or binaries into LLVM modules for each
+ * \c Coal::DeviceInterface for which the program is built.
+ * 
+ * It then contains functions to get the list of kernels available in the
+ * program, using \c Coal::Kernel objects.
+ */
 class Program : public Object
 {
     public:
+        /**
+         * \brief Constructor
+         * \param ctx parent \c Coal::Context
+         */
         Program(Context *ctx);
         ~Program();
 
+        /**
+         * \brief Program type
+         */
         enum Type
         {
-            Invalid,
-            Source,
-            Binary
+            Invalid, /*!< Invalid or unknown, type of a program not already loaded */
+            Source,  /*!< Program made of sources that must be compiled and linked */
+            Binary   /*!< Program made of pre-built binaries that only need to be linked */
         };
 
+        /**
+         * \brief Program state
+         */
         enum State
         {
-            Empty,  /*!< Just created */
-            Loaded, /*!< Source or binary loaded */
-            Built,  /*!< Built */
-            Failed, /*!< Build failed */
+            Empty,   /*!< Just created */
+            Loaded,  /*!< Source or binary loaded */
+            Built,   /*!< Built */
+            Failed,  /*!< Build failed */
         };
 
+        /**
+         * \brief Load sources into the program
+         * 
+         * This function loads the source-code given in \p strings into the
+         * program and sets its type to \c Source.
+         * 
+         * \param count number of strings in \p strings
+         * \param strings array of pointers to strings, either null-terminated 
+         *        or of length given in \p lengths
+         * \param lengths lengths of the strings. If a field is 0, the 
+         *        corresponding string is null-terminated. If \p lengths is
+         *        0, all the strings are null-terminated
+         * \return \c CL_SUCCESS if success, an error code otherwise
+         */
         cl_int loadSources(cl_uint count, const char **strings,
                            const size_t *lengths);
+
+        /**
+         * \brief Load binaries into the program
+         * 
+         * This function allows client application to load a source, retrieve
+         * binaries using \c buildInfo(), and then re-create the same program
+         * (after a restart for example) by giving it a precompiled binary.
+         * 
+         * This function loads the binaries for each device and parse them into
+         * LLVM modules, then sets the program type to \c Binary.
+         * 
+         * \param data array of pointers to binaries, one for each device
+         * \param lengths lengths of the binaries pointed to by \p data
+         * \param binary_status array that will be filled by this function with
+         *        the status of each loaded binary (\c CL_SUCCESS if success)
+         * \param num_devices number of devices for which a binary is loaded
+         * \param device_list list of devices for which the binaries are loaded
+         * \return \c CL_SUCCESS if success, an error code otherwise
+         */
         cl_int loadBinaries(const unsigned char **data, const size_t *lengths,
                             cl_int *binary_status, cl_uint num_devices,
                             DeviceInterface * const*device_list);
+
+        /**
+         * \brief Build the program
+         * 
+         * This function compiles the sources, if any, and then link the
+         * resulting binaries if the devices for which they are compiled asks
+         * \c Coal::Program to do so, using \c Coal::DeviceProgram::linkStdLib().
+         * 
+         * \param options options to pass to the compiler, see the OpenCL 
+         *        specification.
+         * \param pfn_notify callback function called at the end of the build
+         * \param user_data user data given to \p pfn_notify
+         * \param num_devices number of devices for which binaries are being
+         *        built. If it's a source-based program, this can be 0.
+         * \param device_list list of devices for which the program will be built.
+         * \return \c CL_SUCCESS if success, an error code otherwise
+         */
         cl_int build(const char *options,
                      void (CL_CALLBACK *pfn_notify)(cl_program program,
                                                     void *user_data),
                      void *user_data, cl_uint num_devices,
                      DeviceInterface * const*device_list);
 
-        Type type() const;
-        State state() const;
+        Type type() const;   /*!< \brief Type of the program */
+        State state() const; /*!< \brief State of the program */
 
+        /**
+         * \brief Create a kernel given a \p name
+         * \param name name of the kernel to be created
+         * \param errcode_ret return code (\c CL_SUCCESS if success)
+         * \return a \c Coal::Kernel object corresponding to the given \p name
+         */
         Kernel *createKernel(const std::string &name, cl_int *errcode_ret);
+        
+        /**
+         * \brief Create all the kernels of the program
+         * \param errcode_ret return code (\c CL_SUCCESS if success)
+         * \return the list of \c Coal::Kernel objects of this program
+         */
         std::vector<Kernel *> createKernels(cl_int *errcode_ret);
+        
+        /**
+         * \brief Device-specific program
+         * \param device device for which the device-specific program is needed
+         * \return the device-specific program requested, 0 if not found
+         */
         DeviceProgram *deviceDependentProgram(DeviceInterface *device) const;
 
+        /**
+         * \brief Get information about this program
+         * \copydetails Coal::DeviceInterface::info
+         */
         cl_int info(cl_program_info param_name,
                     size_t param_value_size,
                     void *param_value,
                     size_t *param_value_size_ret) const;
+
+        /**
+         * \brief Get build info about this program (log, binaries, etc)
+         * \copydetails Coal::DeviceInterface::info
+         * \param device \c Coal::DeviceInterface for which info is needed
+         */
         cl_int buildInfo(DeviceInterface *device,
                          cl_program_build_info param_name,
                          size_t param_value_size,
diff --git a/src/core/propertylist.h b/src/core/propertylist.h
index 89105cf..d85afbc 100644
--- a/src/core/propertylist.h
+++ b/src/core/propertylist.h
@@ -25,24 +25,95 @@
  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
+/**
+ * \file propertylist.h
+ * \brief Helper macros for \c info() functions
+ * 
+ * The OpenCL API is full of functions like \c clGetXXXInfo(). They all take
+ * the same arguments and are handled the same way. This file contains macros
+ * easing the implementation of these info functions.
+ * 
+ * One info function, using these macros, looks like that:
+ *
+ * \code
+ * cl_int Foo::info(cl_foo_info param_name,
+ *                  size_t param_value_size,
+ *                  void *param_value,
+ *                  size_t *param_value_size_ret) const
+ * {
+ *     void *value = 0;
+ *     size_t value_length = 0;
+ * 
+ *     union {
+ *         cl_uint cl_uint_var;
+ *         cl_context cl_context_var;
+ *     };
+ * 
+ *     switch (param_name)
+ *     {
+ * 		case CL_UINT_PARAM:
+ * 		    SIMPLE_ASSIGN(cl_uint, the_value);
+ * 		    break;
+ * 		case CL_CONTEXT_PARAM:
+ * 		    SIMPLE_ASSIGN(cl_context, a_call());
+ * 		    break;
+ * 		case CL_STRING_PARAM:
+ * 		    STRING_ASSIGN("This is a string");
+ * 		    break;
+ * 		case CL_BINARY_PARAM:
+ * 		    MEM_ASSIGN(sizeof(something), something);
+ * 		    break;
+ *      default:
+ *          return CL_INVALID_VALUE;
+ *     }
+ * 
+ *     if (param_value && param_value_size < value_length)
+ *         return CL_INVALID_VALUE;
+ * 
+ *     if (param_value_size_ret)
+ *         *param_value_size_ret = value_length;
+ * 
+ *     if (param_value)
+ *         std::memcpy(param_value, value, value_length);
+ * 
+ *     return CL_SUCCESS;
+ * }
+ * \endcode
+ */
+
 #ifndef __PROPERTYLIST_H__
 #define __PROPERTYLIST_H__
 
+/**
+ * \brief Assign a value of a given type to the return value
+ * \param type type of the argument
+ * \param _value value to assign
+ */
 #define SIMPLE_ASSIGN(type, _value) do {    \
     value_length = sizeof(type);            \
     type##_var = (type)_value;              \
     value = & type##_var;                   \
 } while (0);
 
+/**
+ * \brief Assign a string to the return value
+ * \param string the string to assign, as a constant
+ */
 #define STRING_ASSIGN(string) do {          \
     static const char str[] = string;       \
     value_length = sizeof(str);             \
     value = (void *)str;                    \
 } while (0);
 
+/**
+ * \brief Assign a memory buffer to the return value
+ * \note the buffer must remain valid after the end of the \c info() call
+ * \param size size of the buffer
+ * \param buf buffer (of type <tt>void *</tt> for instance)
+ */
 #define MEM_ASSIGN(size, buf) do {          \
     value_length = size;                    \
     value = (void *)buf;                    \
 } while (0);
 
-#endif
\ No newline at end of file
+#endif
diff --git a/src/core/sampler.h b/src/core/sampler.h
index 3cf4d10..7f1a3ef 100644
--- a/src/core/sampler.h
+++ b/src/core/sampler.h
@@ -25,6 +25,11 @@
  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
+/**
+ * \file sampler.h
+ * \brief Sampler object
+ */
+
 #ifndef __SAMPLER_H__
 #define __SAMPLER_H__
 
@@ -52,19 +57,45 @@ namespace Coal
 
 class Context;
 
+/**
+ * \brief Sampler
+ * 
+ * This object doesn't do anything intersting, it only converts a set of
+ * host OpenCL constants to constants that will be used by the kernels and
+ * the image reading and writing built-in functions.
+ */
 class Sampler : public Object
 {
     public:
+        /**
+         * \brief Constructor
+         * \param ctx parent \c Coal::Context
+         * \param normalized_coords true if the coords given to the built-in
+         *        image functions are normalized, false otherwise
+         * \param addressing_mode addressing mode used to read images
+         * \param filter_mode filter mode used to read images
+         * \param errcode_ret return code (\c CL_SUCCESS if all is good)
+         */
         Sampler(Context *ctx,
                 cl_bool normalized_coords,
                 cl_addressing_mode addressing_mode,
                 cl_filter_mode filter_mode,
                 cl_int *errcode_ret);
+
+        /**
+         * \brief Simpler constructor
+         * \param ctx parent \c Coal::Context
+         * \param bitfield bitfield already calculated
+         */
         Sampler(Context *ctx,
                 unsigned int bitfield);
 
-        unsigned int bitfield() const;
+        unsigned int bitfield() const; /*!< \brief Bitfield value usable by the kernels */
 
+        /**
+         * \brief Get information about the sampler
+         * \copydetails Coal::DeviceInterface::info
+         */
         cl_int info(cl_sampler_info param_name,
                     size_t param_value_size,
                     void *param_value,