Api documentation updates - added class descriptions for all raster c…

…lasses git-svn-id: http://svn.osgeo.org/qgis/trunk@9226 c8812cc2-4d05-0410-92ff-de0c093fc19c
qgis · Aug 31, 2008 · 401b8e1 · 401b8e1
1 parent 2f03fa0
commit 401b8e1
Show file tree

Hide file tree

Showing 18 changed files with 130 additions and 80 deletions.
diff --git a/src/core/qgsdistancearea.h b/src/core/qgsdistancearea.h
@@ -23,7 +23,7 @@
 class QgsGeometry;
 
 /** \ingroup core
-General purpose distance and area calculator
+General purpose distance and area calculator.
 - calculations are done on ellipsoid
 - it's possible to pass points/features in any CRS, coordinates are transformed
 - two options how to use it

diff --git a/src/core/raster/qgscliptominmaxenhancement.h b/src/core/raster/qgscliptominmaxenhancement.h
@@ -21,6 +21,12 @@ email                : ersts@amnh.org
 
 #include "qgscontrastenhancementfunction.h"
 
+/** \ingroup core
+ * A raster contrast enhancement that will clip a value to the specified min/max range.
+ * For example if a min max range of [10,240] is specified in the constructor, and 
+ * a value of 250 is called using enhanceValue(), the value will be truncated ('clipped') 
+ * to 240.
+ */
 class CORE_EXPORT QgsClipToMinMaxEnhancement : public QgsContrastEnhancementFunction
 {
 

diff --git a/src/core/raster/qgscolorrampshader.h b/src/core/raster/qgscolorrampshader.h
@@ -25,6 +25,9 @@ originally part of the larger QgsRasterLayer class
 
 #include "qgsrastershaderfunction.h"
 
+/** \ingroup core
+ * A ramp shader will color a raster pixel based on a list of values ranges in a ramp.
+ */
 class CORE_EXPORT QgsColorRampShader : public QgsRasterShaderFunction
 {
 

diff --git a/src/core/raster/qgscolortable.h b/src/core/raster/qgscolortable.h
@@ -19,15 +19,6 @@
 
 #include <QVector>
 
-/*
- * Because of performance, this class can store color rules in 2 forms:
- *   1) discrete - vector of descrete values and their colors; can be accessed by index (from 0)
- *   2) ramp - vector of ramps defined by min and max value and a color for min amd max value,
- *             colors between min and max are interpolated linearly.
- *
- * Only one type should be used for one instance.
- *
- */
 
 
 typedef struct
@@ -41,6 +32,18 @@ typedef struct
   unsigned char min_c1, min_c2, min_c3, min_c4;
   unsigned char max_c1, max_c2, max_c3, max_c4;
 } RAMP;
+
+/** \ingroup core
+ * A raster color table contains a list of indexed values and the color associated with each index.
+ * Because of performance, this class can store color rules in 2 forms:
+ *   1) discrete - vector of descrete values and their colors; can be accessed by index (from 0)
+ *   2) ramp - vector of ramps defined by min and max value and a color for min amd max value,
+ *             colors between min and max are interpolated linearly.
+ *
+ * Only one type should be used for one instance.
+ *
+ */
+
 class CORE_EXPORT QgsColorTable
 {
   public:

diff --git a/src/core/raster/qgscontrastenhancement.cpp b/src/core/raster/qgscontrastenhancement.cpp
@@ -28,8 +28,6 @@ class originally created circa 2004 by T.Sutton, Gary E.Sherman, Steve Halasz
 
 QgsContrastEnhancement::QgsContrastEnhancement( QgsRasterDataType theDataType )
 {
-  QgsDebugMsg( "called" );
-
   mLookupTable = 0;
   mContrastEnhancementFunction = 0;
   mEnhancementDirty = false;

diff --git a/src/core/raster/qgscontrastenhancement.h b/src/core/raster/qgscontrastenhancement.h
@@ -25,6 +25,11 @@ class originally created circa 2004 by T.Sutton, Gary E.Sherman, Steve Halasz
 
 class QgsContrastEnhancementFunction;
 
+/** \ingroup core
+ * Manipulates raster pixel values so that they stretch or clip into a
+ * specified numerical range according to the specified
+ * CONTRAST_ENHANCEMENT_ALGORITHM.
+ */
 class CORE_EXPORT QgsContrastEnhancement
 {
 

diff --git a/src/core/raster/qgscontrastenhancementfunction.h b/src/core/raster/qgscontrastenhancementfunction.h
@@ -21,6 +21,12 @@ email                : ersts@amnh.org
 
 #include "qgscontrastenhancement.h"
 
+/** \ingroup core
+ * A contrast enhancement funcion is the base class for all raster contrast enhancements.
+ *
+ * The purpose of a contrast enhancement is to stretch or clip a pixel value into
+ * a specified bounding range.
+ */
 class CORE_EXPORT QgsContrastEnhancementFunction
 {
 

diff --git a/src/core/raster/qgsfreakoutshader.h b/src/core/raster/qgsfreakoutshader.h
@@ -23,6 +23,9 @@ class originally created circa 2004 by T.Sutton, Gary E.Sherman, Steve Halasz
 
 #include "qgsrastershaderfunction.h"
 
+/** \ingroup core
+  * A colorful false color shader that will frighten your granny and make your dogs howl.
+  */
 class CORE_EXPORT QgsFreakOutShader : public QgsRasterShaderFunction
 {
 

diff --git a/src/core/raster/qgslinearminmaxenhancement.h b/src/core/raster/qgslinearminmaxenhancement.h
@@ -21,6 +21,9 @@ email                : ersts@amnh.org
 
 #include "qgscontrastenhancementfunction.h"
 
+/** \ingroup core
+  * A colour enhancement function that performs a linear stretch between min and max.
+  */
 class CORE_EXPORT QgsLinearMinMaxEnhancement : public QgsContrastEnhancementFunction
 {
 

diff --git a/src/core/raster/qgslinearminmaxenhancementwithclip.h b/src/core/raster/qgslinearminmaxenhancementwithclip.h
@@ -21,6 +21,10 @@ email                : ersts@amnh.org
 
 #include "qgscontrastenhancementfunction.h"
 
+/** \ingroup core
+ * A linear stretch enhancement that first clips to min max and then stretches
+ * linearly between min and max.
+ */
 class CORE_EXPORT QgsLinearMinMaxEnhancementWithClip : public QgsContrastEnhancementFunction
 {
 

diff --git a/src/core/raster/qgspseudocolorshader.h b/src/core/raster/qgspseudocolorshader.h
@@ -23,6 +23,9 @@ class originally created circa 2004 by T.Sutton, Gary E.Sherman, Steve Halasz
 
 #include "qgsrastershaderfunction.h"
 
+/** \ingroup core
+ * A raster color shader that highlighs low values in blue and high values in red.
+ */
 class CORE_EXPORT QgsPseudoColorShader : public QgsRasterShaderFunction
 {
 

diff --git a/src/core/raster/qgsrasterbandstats.h b/src/core/raster/qgsrasterbandstats.h
@@ -16,11 +16,6 @@
  ***************************************************************************/
 /* $Id: qgsrasterlayer.h 4380 2005-12-26 23:37:50Z timlinux $ */
 
-/** \file qgsrasterbandstats
- *  \brief This class provides statistics for a given raster band.
- *
- *  The qgsrasterbandstats holds various stats relating to a given raster band.
- */
 #ifndef QGSRASTERBANDSTATS
 #define QGSRASTERBANDSTATS
 
@@ -30,7 +25,8 @@
 #include <limits>
 
 #include "qgscolortable.h"
-/** \brief The RasterBandStats struct is a container for statistics about a single
+/** \ingroup core
+ * The RasterBandStats struct is a container for statistics about a single
  * raster band.
  */
 class CORE_EXPORT QgsRasterBandStats

diff --git a/src/core/raster/qgsrasterlayer.h b/src/core/raster/qgsrasterlayer.h
@@ -16,9 +16,61 @@
  ***************************************************************************/
 /* $Id$ */
 
-/** \file qgsrasterlayer.h
- *  \brief This class provides qgis with the ability to render raster datasets
- *  onto the mapcanvas
+
+
+#ifndef QGSRASTERLAYER_H
+#define QGSRASTERLAYER_H
+
+//
+// Includes
+//
+
+#include <QColor>
+#include <QDateTime>
+#include <QVector>
+#include <QList>
+#include <QMap>
+
+#include "qgis.h"
+#include "qgspoint.h"
+#include "qgsmaplayer.h"
+#include "qgscontrastenhancement.h"
+#include "qgsrastertransparency.h"
+#include "qgsrastershader.h"
+#include "qgscolorrampshader.h"
+#include "qgsrastershaderfunction.h"
+#include "qgsrasterdataprovider.h"
+
+
+#define CPL_SUPRESS_CPLUSPLUS
+#include <gdal.h>
+/** \ingroup core
+ * A call back function for showing progress of gdal operations.
+ */
+int CPL_STDCALL progressCallback( double dfComplete,
+                                  const char *pszMessage,
+                                  void * pProgressArg );
+
+
+//
+// Forward declarations
+//
+class QgsColorTable;
+class QgsMapToPixel;
+class QgsRect;
+class QgsRasterBandStats;
+class QgsRasterPyramid;
+class QgsRasterLayerProperties;
+struct QgsRasterViewPort;
+class QImage;
+class QPixmap;
+class QSlider;
+class QLibrary;
+
+
+/** \ingroup core
+ *  This class provides qgis with the ability to render raster datasets
+ *  onto the mapcanvas.
  *
  *  The qgsrasterlayer class makes use of gdal for data io, and thus supports
  *  any gdal supported format. The constructor attempts to infer what type of
@@ -57,21 +109,29 @@
  *
  *  Sample usage of the QgsRasterLayer class:
  *
+ * \code
  *     QString myFileNameQString = "/path/to/file";
  *     QFileInfo myFileInfo(myFileNameQString);
  *     QString myBaseNameQString = myFileInfo.baseName();
  *     QgsRasterLayer *myRasterLayer = new QgsRasterLayer(myFileNameQString, myBaseNameQString);
  *
+ * \endcode
+ *
  *  In order to automate redrawing of a raster layer, you should like it to a map canvas like this :
  *
+ * \code
  *     QObject::connect( myRasterLayer, SIGNAL(repaintRequested()), mapCanvas, SLOT(refresh()) );
+ * \endcode
  *
  *  A raster layer can also export its legend as a pixmap:
  *
+ * \code
  *     QPixmap myQPixmap = myRasterLayer->legendPixmap();
+ * \endcode
  *
  * Once a layer has been created you can find out what type of layer it is (GRAY_OR_UNDEFINED, PALETTE or MULTIBAND):
  *
+ * \code
  *    if (rasterLayer->getRasterLayerType()==QgsRasterLayer::MULTIBAND)
  *    {
  *      //do something
@@ -84,10 +144,12 @@
  *    {
  *      //do something.
  *    }
+ * \endcode
  *
  * You can combine layer type detection with the setDrawingStyle method to override the default drawing style assigned
  * when a layer is loaded:
  *
+  * \code
  *    if (rasterLayer->getRasterLayerType()==QgsRasterLayer::MULTIBAND)
  *    {
  *       myRasterLayer->setDrawingStyle(QgsRasterLayer::MULTI_BAND_SINGLE_BAND_PSEUDO_COLOR);
@@ -100,6 +162,7 @@
  *    {
  *      myRasterLayer->setDrawingStyle(QgsRasterLayer::SINGLE_BAND_PSEUDO_COLOR);
  *    }
+ * \endcode
  *
  *  Raster layers can also have an arbitrary level of transparency defined, and have their
  *  color palettes inverted using the setTransparency and setInvertHistogramFlag methods.
@@ -116,62 +179,6 @@
  *  methods.
  */
 
-
-#ifndef QGSRASTERLAYER_H
-#define QGSRASTERLAYER_H
-
-//
-// Includes
-//
-
-#include <QColor>
-#include <QDateTime>
-#include <QVector>
-#include <QList>
-#include <QMap>
-
-#include "qgis.h"
-#include "qgspoint.h"
-#include "qgsmaplayer.h"
-#include "qgscontrastenhancement.h"
-#include "qgsrastertransparency.h"
-#include "qgsrastershader.h"
-#include "qgscolorrampshader.h"
-#include "qgsrastershaderfunction.h"
-#include "qgsrasterdataprovider.h"
-
-
-#define CPL_SUPRESS_CPLUSPLUS
-#include <gdal.h>
-
-int CPL_STDCALL progressCallback( double dfComplete,
-                                  const char *pszMessage,
-                                  void * pProgressArg );
-
-
-//
-// Forward declarations
-//
-class QgsColorTable;
-class QgsMapToPixel;
-class QgsRect;
-class QgsRasterBandStats;
-class QgsRasterPyramid;
-class QgsRasterLayerProperties;
-struct QgsRasterViewPort;
-class QImage;
-class QPixmap;
-class QSlider;
-class QLibrary;
-
-
-
-
-/*! \class QgsRasterLayer
- *  \brief This class provides qgis with the ability to render raster datasets
- *  onto the mapcanvas..
- */
-
 class CORE_EXPORT QgsRasterLayer : public QgsMapLayer
 {
     Q_OBJECT

diff --git a/src/core/raster/qgsrasterpyramid.h b/src/core/raster/qgsrasterpyramid.h
@@ -17,7 +17,9 @@
  ***************************************************************************/
 #ifndef QGSRASTERPYRAMID
 #define QGSRASTERPYRAMID
-/** \brief This struct is used to store pyramid info for the raster layer. */
+/** \ingroup core
+  * This struct is used to store pyramid info for the raster layer. 
+  */
 class CORE_EXPORT QgsRasterPyramid
 {
   public:

diff --git a/src/core/raster/qgsrastershader.h b/src/core/raster/qgsrastershader.h
@@ -22,6 +22,9 @@ email                : ersts@amnh.org
 
 #include "qgsrastershaderfunction.h"
 
+/** \ingroup core
+ * Interface for all raster shaders.
+ */
 class CORE_EXPORT QgsRasterShader
 {
 

diff --git a/src/core/raster/qgsrastershaderfunction.h b/src/core/raster/qgsrastershaderfunction.h
@@ -19,6 +19,10 @@ email                : ersts@amnh.org
 
 #ifndef QGSRASTERSHADERFUNCTION_H
 #define QGSRASTERSHADERFUNCTION_H
+/** \ingroup core
+ * The raster shade function applies a shader to a pixel at render time -
+ * typically used to render grayscale images as false color.
+ */
 
 class CORE_EXPORT QgsRasterShaderFunction
 {

diff --git a/src/core/raster/qgsrastertransparency.h b/src/core/raster/qgsrastertransparency.h
@@ -18,6 +18,10 @@ email                : ersts@amnh.org
 #ifndef QGSRASTERTRANSPARENCY_H
 #define QGSRASTERTRANSPARENCY_H
 
+/** \ingroup core
+ * Defines the list of pixel values to be considered as transparent or semi
+ * transparent when rendering rasters.
+ */
 class CORE_EXPORT QgsRasterTransparency
 {
 

diff --git a/src/core/raster/qgsrasterviewport.h b/src/core/raster/qgsrasterviewport.h
@@ -20,8 +20,8 @@
 
 #include <qgspoint.h>
 
-/** \file qgsrasterviewport.h
- *  \brief This class provides details of the viewable area that a raster will
+/** \ingroup core
+ *  This class provides details of the viewable area that a raster will
  *  be rendered into.
  *
  *  The qgsrasterviewport class sets up a viewport / area of interest to be used