comments (#37)

Add doc comments to lots of files

Author: ChristianBeilschmidt

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2018 Database Research Group of the University of Marburg
+Copyright (c) 2014-2020 Database Research Group of the University of Marburg
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

src/datatypes/colorizer.h

@@ -10,10 +10,19 @@
 
 using color_t = uint32_t;
 
+/// Create a color from rgba bytes
 auto color_from_rgba(uint8_t r, uint8_t g, uint8_t b, uint8_t a = 255) noexcept -> color_t;
+
+/// Extracts the red portion (byte) of a color
 auto r_from_color(color_t color) -> uint8_t;
+
+/// Extracts the green portion (byte) of a color
 auto g_from_color(color_t color) -> uint8_t;
+
+/// Extracts the blue portion (byte) of a color
 auto b_from_color(color_t color) -> uint8_t;
+
+/// Extracts the alpha portion (byte) of a color
 auto a_from_color(color_t color) -> uint8_t;
 
 class Unit;
@@ -27,13 +36,19 @@ static color_t defaultDefaultColor = color_from_rgba(255, 0, 255, 0);
  */
 class Colorizer {
     public:
+        /**
+         * A breakpoint that maps a value to a color
+         */
         struct Breakpoint {
             Breakpoint(double v, color_t c) : value(v), color(c) {}
 
             double value;
             color_t color;
         };
 
+        /**
+         * An interpolation method between break points
+         */
         enum class Interpolation {
                 NEAREST,
                 LINEAR,
@@ -42,15 +57,27 @@ class Colorizer {
         };
         using ColorTable = std::vector<Breakpoint>;
 
+        /**
+         * Create a new colorizer by specifying a color breakpoint table, an interpolation method, a no data color and a default color
+         */
         explicit Colorizer(ColorTable table, Interpolation interpolation = Interpolation::LINEAR,
                            color_t nodataColor = defaultNoDataColor, color_t defaultColor = defaultDefaultColor);
 
         virtual ~Colorizer();
 
+        /**
+         * Fill a palette of `num_colors` colors by using the colorizer's breakpoints
+         */
         void fillPalette(color_t *colors, unsigned int num_colors, double min, double max) const;
 
+        /**
+         * Serialize this colorizer to a JSON string
+         */
         std::string toJson() const;
 
+        /**
+         * Retrieve the interpolation enum variant
+         */
         auto getInterpolation() const -> Interpolation { return this->interpolation; }
 
         /**
@@ -73,18 +100,30 @@ class Colorizer {
          */
         static const Colorizer &error();
 
+        /**
+         * Retrieve the minimum value of the color breakpoint table
+         */
         double minValue() const {
             return table.front().value;
         }
 
+        /**
+         * Retrieve the maximum value of the color breakpoint table
+         */
         double maxValue() const {
             return table.back().value;
         }
 
+        /**
+         * Retrieve no data color
+         */
         color_t getNoDataColor() const {
             return nodataColor;
         }
 
+        /**
+         * Retrieve the default color
+         */
         color_t getDefaultColor() const {
             return defaultColor;
         }

src/datatypes/plots/histogram.h

@@ -8,42 +8,85 @@
 #include <datatypes/plot.h>
 
 /**
- * This class models a one dimensional histograms with variable number of buckets
+ * This class models a one dimensional histogram with a variable number of buckets
  */
 class Histogram : public GenericPlot {
     public:
+        /**
+         * Construct a histogram by specifying the number of buckets and its range.
+         */
         Histogram(unsigned long number_of_buckets, double min, double max);
+
+        /**
+         * Construct a histogram by specifying the number of buckets and its range.
+         * Furthermore, specify a unit for the X axis
+         */
         Histogram(unsigned long number_of_buckets, double min, double max, const Unit &unit);
+
+        /**
+         * Construct a histogram by specifying the number of buckets and its range.
+         * Furthermore, specify the unit string for the X axis
+         */
         Histogram(unsigned long number_of_buckets, double min, double max, std::string unit_string);
 
+        /**
+         * Deserialize a histogram from a binary buffer
+         */
         explicit Histogram(BinaryReadBuffer &buffer);
 
         ~Histogram() override;
 
+        /**
+         * Compute a display X axis unit string from a unit
+         */
         static auto compute_unit_string(const Unit &unit) -> std::string;
 
+        /**
+         * Increase a histogram bucket by a value in which it fits
+         */
         void inc(double value);
 
+        /**
+         * Increase the histogram's no data counter
+         */
         void incNoData();
 
+        /**
+         * Serialize the histogram to a JSON string
+         */
         const std::string toJSON() const override;
 
+        /**
+         * Retrieve the number of values for one bucket
+         */
         int getCountForBucket(unsigned long bucket) {
             return counts.at(bucket);
         }
 
+        /**
+         * Retrieve the number of no data values
+         */
         int getNoDataCount() {
             return nodata_count;
         }
 
+        /**
+         * Retrieve the minimum value of the histogram's range
+         */
         double getMin() {
             return min;
         }
 
+        /**
+         * Retrieve the maximum value of the histogram's range
+         */
         double getMax() {
             return max;
         }
 
+        /**
+         * Retrieve the number of buckets
+         */
         unsigned long getNumberOfBuckets() {
             return counts.size();
         }
@@ -68,8 +111,14 @@ class Histogram : public GenericPlot {
          */
         void addMarker(double bucket, const std::string &label);
 
+        /**
+         * Clone the histogram by copying its internals
+         */
         std::unique_ptr<GenericPlot> clone() const override;
 
+        /**
+         * Serialize the histogram into a binary buffer
+         */
         void serialize(BinaryWriteBuffer &buffer, bool is_persistent_memory) const override;
 
     private:

src/datatypes/raster/raster_priv.h

@@ -9,31 +9,61 @@
 template<typename T, int dimensions>
 class Raster : public GenericRaster {
     public:
+        /**
+         * Create a raster using a `DataDescription`, a `SpatioTemporalReference` as well as its `width`, `height` and `depth`
+         */
         Raster(const DataDescription &datadescription, const SpatioTemporalReference &stref, uint32_t width,
                uint32_t height, uint32_t depth);
 
+        /**
+         * Destructor for the raster
+         */
         virtual ~Raster();
 
+        /**
+         * Retrieve the byte size of the raster's pixels
+         */
         virtual size_t getDataSize() const { return sizeof(T) * getPixelCount(); };
 
+        /**
+         * Retrieve the byte size of
+         */
         virtual int getBPP() { return sizeof(T); }
 
+        /**
+         * Change representation to CPU or GPU
+         */
         virtual void setRepresentation(Representation);
 
+        /**
+         * Access the data as a const void pointer
+         */
         virtual const void *getData() {
             setRepresentation(GenericRaster::Representation::CPU);
             return (void *) data;
         };
 
+        /**
+         * Access the data as a void pointer
+         */
         virtual void *getDataForWriting() {
             setRepresentation(GenericRaster::Representation::CPU);
             return (void *) data;
         };
 
+        /**
+         * Retrieve the underlying OpenCL Buffer if it exists
+         */
         virtual cl::Buffer *getCLBuffer() { return clbuffer; };
 
+        /**
+         * Retrieve the underlying OpenCL Info Buffer if it exists
+         */
         virtual cl::Buffer *getCLInfoBuffer() { return clbuffer_info; };
 
+        /**
+         * Return the total byte size of this raster
+         */
         virtual size_t get_byte_size() const {
             return GenericRaster::get_byte_size() + getDataSize() + sizeof(T *) + sizeof(void *) +
                    2 * sizeof(cl::Buffer *);
@@ -54,52 +84,115 @@ class RasterOperator;
 template<typename T>
 class Raster2D : public Raster<T, 2> {
     public:
+        /**
+         * Create a raster using a `DataDescription`, a `SpatioTemporalReference` as well as its `width` and `height`
+         */
         Raster2D(const DataDescription &datadescription, const SpatioTemporalReference &stref, uint32_t width,
                  uint32_t height, uint32_t depth = 0);
 
+        /**
+         * Destructor of `Raster2D`
+         */
         virtual ~Raster2D();
 
+        /**
+         * Create a Netpbm grayscale image file
+         */
         virtual void toPGM(const char *filename, bool avg);
 
+        /**
+        * Create a YUV video file
+        */
         virtual void toYUV(const char *filename);
 
+        /**
+        * Create a Portable Network Graphics byte stream
+        */
         virtual void toPNG(std::ostream &output, const Colorizer &colorizer, bool flipx = false, bool flipy = false,
                            Raster2D<uint8_t> *overlay = nullptr);
 
+        /**
+         * Create a JPEG file
+         */
         virtual void toJPEG(const char *filename, const Colorizer &colorizer, bool flipx = false, bool flipy = false);
 
+        /**
+         * Create a GDAL file based on a driver
+         */
         virtual void toGDAL(const char *filename, const char *driver, bool flipx = false, bool flipy = false);
 
+        /**
+         * Clears all pixels and sets a value
+         */
         virtual void clear(double value);
 
+        /**
+         * Copies this raster's values to an offset of a destination raster
+         */
         virtual void blit(const GenericRaster *raster, int x, int y = 0, int z = 0);
 
+        /**
+         * Modifies this raster by cutting out a rectangular portion
+         */
         virtual std::unique_ptr<GenericRaster> cut(int x, int y, int z, int width, int height, int depths);
 
+        /**
+         *  Resizes this raster with scale parameters
+         */
         virtual std::unique_ptr<GenericRaster> scale(int width, int height = 0, int depth = 0);
 
+        /**
+         * Flips the current raster along axes
+         */
         virtual std::unique_ptr<GenericRaster> flip(bool flipx, bool flipy);
 
+        /**
+         * Modifies this raster by cutting out the rectangular region of the query rectangle `qrect`
+         */
         virtual std::unique_ptr<GenericRaster> fitToQueryRectangle(const QueryRectangle &qrect);
 
+        /**
+         * Prints a series of chars to a region of this raster
+         */
         virtual void print(int x, int y, double value, const char *text, int maxlen = -1);
 
+        /**
+         * Retrieves a pixel values as a double
+         */
         virtual double getAsDouble(int x, int y = 0, int z = 0) const;
 
+        /**
+         * Retrieves a pixel value
+         *
+         * Performs no out of bounds check
+         */
         T get(int x, int y) const {
             return data[(size_t) y * width + x];
         }
 
+        /**
+         * Retrieves a pixel value and returns the default value `def` if the call is out of bounds
+         */
         T getSafe(int x, int y, T def = 0) const {
             if (x >= 0 && y >= 0 && (uint32_t) x < width && (uint32_t) y < height)
                 return data[(size_t) y * width + x];
             return def;
         }
 
+        /**
+         * Writes a value to a pixel position
+         *
+         * Performs no out of bounds check
+         */
         void set(int x, int y, T value) {
             data[(size_t) y * width + x] = value;
         }
 
+        /**
+         * Writes a value to a pixel position
+         *
+         * Performs no action if the position is out of bounds
+         */
         void setSafe(int x, int y, T value) {
             if (x >= 0 && y >= 0 && (uint32_t) x < width && (uint32_t) y < height)
                 data[(size_t) y * width + x] = value;