Add, refactor & cleanup documentation

arrayfire · Jun 17, 2019 · d47cc0b · d47cc0b
1 parent 938b452
commit d47cc0b
Show file tree

Hide file tree

Showing 13 changed files with 65 additions and 53 deletions.
diff --git a/include/ComputeCopy.h b/include/ComputeCopy.h
@@ -49,17 +49,20 @@ extern "C" {
 #endif
 
 
-/** A backend-agnostic handle to a compute memory resource originating from an OpenGL resource.
-
-    - cudaGraphicsResource in CUDA
-    - cl_mem in OpenCL
-    - unsigned from standard cpu
-  */
+/// A backend-agnostic handle to a compute memory resource originating
+/// from an OpenGL resource.
+///
+/// - cudaGraphicsResource in CUDA
+/// - cl_mem in OpenCL
+/// - unsigned from standard cpu
 #if defined(USE_FORGE_CPU_COPY_HELPERS)
+/// OpenGL interop with CPU uses regular OpenGL buffer
 typedef unsigned GfxResourceHandle;
 #elif defined(USE_FORGE_CUDA_COPY_HELPERS)
+/// OpenGL interop with CUDA uses an opaque CUDA object
 typedef cudaGraphicsResource* GfxResourceHandle;
 #elif defined(USE_FORGE_OPENCL_COPY_HELPERS)
+/// OpenGL interop with OpenCL uses cl_mem object
 typedef cl_mem GfxResourceHandle;
 #endif
 
@@ -72,11 +75,13 @@ typedef cl_mem GfxResourceHandle;
   */
 typedef void* ComputeResourceHandle;
 
+/// Enum to indicate if OpenCL buffer is a PBO or VBO
 typedef enum {
     FORGE_IMAGE_BUFFER  = 0,     ///< OpenGL Pixel Buffer Object
     FORGE_VERTEX_BUFFER = 1      ///< OpenGL Vertex Buffer Object
 } BufferType;
 
+/// A tuple object of GfxResourceHandle and \ref BufferType
 typedef struct {
     GfxResourceHandle mId;
     BufferType mTarget;

diff --git a/include/fg/chart.h b/include/fg/chart.h
@@ -80,8 +80,6 @@ FGAPI fg_err fg_set_chart_axes_titles(fg_chart pHandle,
    \param[in] pYmax is y-axis maximum data value
    \param[in] pZmin is z-axis minimum data value
    \param[in] pZmax is z-axis maximum data value
-
-   \ingroup chart_functions
  */
 FGAPI fg_err fg_set_chart_axes_limits(fg_chart pHandle,
                                       const float pXmin, const float pXmax,
@@ -111,8 +109,6 @@ FGAPI fg_err fg_set_chart_label_format(fg_chart pHandle, const char* pXFormat,
    \param[out] pZmin is z-axis minimum data value
    \param[out] pZmax is z-axis maximum data value
    \param[in] pHandle is chart handle
-
-   \ingroup chart_functions
  */
 FGAPI fg_err fg_get_chart_axes_limits(float* pXmin, float* pXmax,
                                       float* pYmin, float* pYmax,
@@ -305,8 +301,6 @@ namespace forge
 {
 
 /**
-   \class Chart
-
    \brief Chart is base canvas where other plottable objects are rendered.
 
    Charts come in two types:

diff --git a/include/fg/defines.h b/include/fg/defines.h
@@ -34,15 +34,31 @@
 
 #include <cstdlib>
 
+/// \brief Window handle
 typedef void* fg_window;
+
+/// \brief Font handle
 typedef void* fg_font;
+
+/// \brief Chart handle
 typedef void* fg_chart;
+
+/// \brief Image handle
 typedef void* fg_image;
+
+/// \brief Histogram handle
 typedef void* fg_histogram;
+
+/// \brief Plot handle
 typedef void* fg_plot;
+
+/// \brief Surface handle
 typedef void* fg_surface;
+
+/// \brief Vector Field handle
 typedef void* fg_vector_field;
 
+/// \brief Return Error Codes for Forge C API
 typedef enum {
     FG_ERR_NONE           = 0,              ///< Fuction returned successfully.
     /*
@@ -102,6 +118,7 @@ typedef enum {
     FG_ERR_UNKNOWN        = 9003            ///< Unkown error
 } fg_err;
 
+/// \brief Image Channel Formats
 typedef enum {
     FG_GRAYSCALE = 100,                     ///< Single channel
     FG_RG        = 200,                     ///< Three(Red, Green & Blue) channels
@@ -111,14 +128,13 @@ typedef enum {
     FG_BGRA      = 401                      ///< Four(Red, Green, Blue & Alpha) channels
 } fg_channel_format;
 
+/// \brief Chart dimensionality i.e. 2D or 3D
 typedef enum {
     FG_CHART_2D = 2,                        ///< Two dimensional charts
     FG_CHART_3D = 3                         ///< Three dimensional charts
 } fg_chart_type;
 
-/**
-   Color maps
- */
+/// \brief Color Maps
 typedef enum {
     FG_COLOR_MAP_DEFAULT  =  0,              ///< Default [0-255] grayscale colormap
     FG_COLOR_MAP_SPECTRUM =  1,              ///< Visual spectrum (390nm-830nm) in sRGB colorspace
@@ -133,6 +149,7 @@ typedef enum {
     FG_COLOR_MAP_VIRIDIS  = 10,              ///< perceptually uniform shades of blue-green-yellow
 } fg_color_map;
 
+/// \brief Color Constants
 typedef enum {
     FG_RED     = 0xFF0000FF,
     FG_GREEN   = 0x00FF00FF,
@@ -144,6 +161,7 @@ typedef enum {
     FG_BLACK   = 0x000000FF
 } fg_color;
 
+/// \brief Enum representation of internal data types
 typedef enum {
     FG_INT8    = 0,                                ///< Signed byte (8-bits)
     FG_UINT8   = 1,                                ///< Unsigned byte (8-bits)
@@ -154,12 +172,14 @@ typedef enum {
     FG_UINT16  = 6                                 ///< Unsigned integer (16-bits)
 } fg_dtype;
 
+/// \brief Plot Style
 typedef enum {
     FG_PLOT_LINE         = 0,                    ///< Line plot
     FG_PLOT_SCATTER      = 1,                    ///< Scatter plot
     FG_PLOT_SURFACE      = 2                     ///< Surface plot
 } fg_plot_type;
 
+/// \brief Markers rendered as sprites
 typedef enum {
     FG_MARKER_NONE         = 0,                    ///< No marker
     FG_MARKER_POINT        = 1,                    ///< Point marker
@@ -172,8 +192,9 @@ typedef enum {
 } fg_marker_type;
 
 #ifdef __cplusplus
-namespace forge
-{
+
+/// \brief Forge API namespace
+namespace forge {
     typedef fg_err ErrorCode;
     typedef fg_channel_format ChannelFormat;
     typedef fg_chart_type ChartType;
@@ -182,6 +203,7 @@ namespace forge
     typedef fg_plot_type PlotType;
     typedef fg_marker_type MarkerType;
 
+    /// \brief Alias Enum to \ref fg_dtype enum
     typedef enum {
         s8  = FG_INT8,
         u8  = FG_UINT8,

diff --git a/include/fg/exception.h b/include/fg/exception.h
@@ -18,6 +18,7 @@
 namespace forge
 {
 
+/// \brief Error is exception object thrown by forge for internal errors
 class FGAPI Error : public std::exception
 {
 private:
@@ -59,7 +60,18 @@ class FGAPI Error : public std::exception
 extern "C" {
 #endif
 
+/**
+    Fetch the last error's error code
+
+    \ingroup util_functions
+ */
 FGAPI void fg_get_last_error(char **msg, int *len);
+
+/**
+    Fetch the string message associated to given error code
+
+    \ingroup util_functions
+ */
 FGAPI const char * fg_err_to_string(const fg_err err);
 
 #ifdef __cplusplus

diff --git a/include/fg/font.h b/include/fg/font.h
@@ -78,11 +78,7 @@ FGAPI fg_err fg_load_system_font(fg_font pFont, const char* const pFontName);
 namespace forge
 {
 
-/**
-   \class Font
-
-   \brief Font object is essentially a resource handler for the specific font you want to use
- */
+/// \brief Font object is a resource handler for the font you want to use
 class Font {
     private:
         fg_font mValue;

diff --git a/include/fg/histogram.h b/include/fg/histogram.h
@@ -155,11 +155,7 @@ FGAPI fg_err fg_get_histogram_alpha_buffer_size(unsigned* pOut, const fg_histogr
 namespace forge
 {
 
-/**
-   \class Histogram
-
-   \brief Histogram is a bar graph to display data frequencey.
- */
+/// \brief Histogram is a bar graph to display data frequencey.
 class Histogram {
     private:
         fg_histogram mValue;

diff --git a/include/fg/image.h b/include/fg/image.h
@@ -166,11 +166,7 @@ namespace forge
 
 class Window;
 
-/**
-   \class Image
-
-   \brief Image is plain rendering of an image over the window or sub-region of it.
- */
+/// \brief Image helps rendering an image in a window
 class Image {
     private:
         fg_image mValue;

diff --git a/include/fg/plot.h b/include/fg/plot.h
@@ -190,11 +190,7 @@ FGAPI fg_err fg_get_plot_radii_buffer_size(unsigned* pOut, const fg_plot pPlot);
 namespace forge
 {
 
-/**
-   \class Plot
-
-   \brief Plot is a line graph to display two dimensional data.
- */
+/// \brief Plot is a line graph to display two dimensional data.
 class Plot {
     private:
         fg_plot mValue;

diff --git a/include/fg/surface.h b/include/fg/surface.h
@@ -155,11 +155,7 @@ FGAPI fg_err fg_get_surface_alpha_buffer_size(unsigned* pOut, const fg_surface p
 namespace forge
 {
 
-/**
-   \class Surface
-
-   \brief Surface is a graph to display three dimensional data.
- */
+/// \brief Surface is a graph to display three dimensional data.
 class Surface {
     private:
         fg_surface mValue;

diff --git a/include/fg/update_buffer.h b/include/fg/update_buffer.h
@@ -68,6 +68,8 @@ namespace forge
     \param[in] pBufferId is the buffer identifier
     \param[in] pBufferSize is the buffer size in bytes
     \param[in] pBufferData is the pointer of the host side memory
+
+    \ingroup util_functions
  */
 FGAPI void updateVertexBuffer(const unsigned pBufferId,
                               const size_t pBufferSize,
@@ -79,13 +81,17 @@ FGAPI void updateVertexBuffer(const unsigned pBufferId,
     \param[in] pBufferId is the buffer identifier
     \param[in] pBufferSize is the buffer size in bytes
     \param[in] pBufferData is the pointer of the host side memory
+
+    \ingroup util_functions
  */
 FGAPI void updatePixelBuffer(const unsigned pBufferId,
                              const size_t pBufferSize,
                              const void* pBufferData);
 
 /**
     Sync all rendering operations till this point
+
+    \ingroup util_functions
  */
 FGAPI void finish();
 

diff --git a/include/fg/vector_field.h b/include/fg/vector_field.h
@@ -172,11 +172,7 @@ FGAPI fg_err fg_get_vector_field_direction_buffer_size(unsigned* pOut, const fg_
 namespace forge
 {
 
-/**
-   \class VectorField
-
-   \brief VectorField is a line graph to display two dimensional data.
- */
+/// \brief VectorField is a line graph to display two dimensional data.
 class VectorField {
     private:
         fg_vector_field mValue;

diff --git a/include/fg/window.h b/include/fg/window.h
@@ -292,11 +292,7 @@ FGAPI fg_err fg_save_window_framebuffer(const char* pFullPath, const fg_window p
 namespace forge
 {
 
-/**
-   \class Window
-
-   \brief Window is where other objects such as Images, Plots etc. are rendered.
- */
+/// \brief Window is where objects such as Images, Plots etc. are rendered.
 class Window {
     private:
         fg_window mValue;

diff --git a/include/forge.h b/include/forge.h
@@ -14,8 +14,9 @@
 \defgroup c_api_functions C API functions
 Categorically divided into groups based on the renderable
 they are related to.
-@{
 
+\addtogroup c_api_functions
+@{
     \defgroup chart_functions Chart
     \defgroup font_functions Font
     \defgroup hist_functions Histogram