Add and update document strings

cgiutil.h

@@ -49,7 +49,9 @@ extern "C" {
 
 enum MS_REQUEST_TYPE {MS_GET_REQUEST, MS_POST_REQUEST};
 
-/* structure to hold request information */
+/**
+Class for programming OWS services
+*/
 typedef struct {
 #ifndef SWIG
   char **ParamNames;
@@ -59,17 +61,15 @@ typedef struct {
 #ifdef SWIG
   %immutable;
 #endif
-  int NumParams;
+  int NumParams; ///< The number of querystring parameters
 #ifdef SWIG
   %mutable;
 #endif
 
-  enum MS_REQUEST_TYPE type;
-  char *contenttype;
-
-  char *postrequest;
-
-  char *httpcookiedata;
+  enum MS_REQUEST_TYPE type; ///< A :ref:`request type constant<mapfile-constants-requesttype>`
+  char *contenttype; ///< The content type of the request
+  char *postrequest; ///< Any POST data request
+  char *httpcookiedata; ///< Any cookie data associated with the request
 } cgiRequestObj;
 
 

maperror.h

@@ -123,11 +123,11 @@ Errors are managed as a chained list with the first item being the most recent e
   /*
   ** Function prototypes
   */
-  MS_DLL_EXPORT errorObj *msGetErrorObj(void);
-  MS_DLL_EXPORT void msResetErrorList(void);
-  MS_DLL_EXPORT char *msGetVersion(void);
-  MS_DLL_EXPORT int  msGetVersionInt(void);
-  MS_DLL_EXPORT char *msGetErrorString(const char *delimiter);
+  MS_DLL_EXPORT errorObj *msGetErrorObj(void); ///< Get the MapServer error object
+  MS_DLL_EXPORT void msResetErrorList(void); ///< Clear the list of error objects
+  MS_DLL_EXPORT char *msGetVersion(void); ///< Returns a string containing MapServer version information, and details on what optional components are built in - the same report as produced by ``mapserv -v``
+  MS_DLL_EXPORT int  msGetVersionInt(void); ///< Returns the MapServer version number (x.y.z) as an integer (x*10000 + y*100 + z) e.g. V7.4.2 would return 70402
+  MS_DLL_EXPORT char *msGetErrorString(const char *delimiter); ///< Return a string of all errors
 
 #ifndef SWIG
   MS_DLL_EXPORT void msSetError(int code, const char *message, const char *routine, ...) MS_PRINT_FUNC_FORMAT(2,4) ;

mapfile.c

@@ -7181,7 +7181,6 @@ void initResultCache(resultCacheObj *resultcache)
     resultcache->cachesize = 0;
     resultcache->bounds.minx = resultcache->bounds.miny = resultcache->bounds.maxx = resultcache->bounds.maxy = -1;
     resultcache->previousBounds = resultcache->bounds;
-    resultcache->usegetshape = MS_FALSE;
   }
 }
 

mapserver.h

@@ -859,16 +859,16 @@ The :ref:`OUTPUTFORMAT <outputformat>` object
     %immutable;
 #endif /* SWIG */
     int  numformatoptions; ///< The number of option values set on this format - can be used to 
-                           ///< iterate over the options array in conjunction with ``getOptionAt``
+                           ///< iterate over the options array in conjunction with :func:`outputFormatObj.getOptionAt`
 #ifdef SWIG
     %mutable;
 #endif /* SWIG */
     char *name; ///< See :ref:`NAME <mapfile-outputformat-name>`
     char *mimetype; ///< See :ref:`MIMETYPE <mapfile-outputformat-mimetype>`
     char *driver; ///< See :ref:`DRIVER <mapfile-outputformat-driver>`
     char *extension; ///< See :ref:`EXTENSION <mapfile-outputformat-extension>`
-    int  renderer;  ///< ``MS_RENDER_WITH_*`` value - normally set internally based on the driver and some other setting in the constructor.
-    int  imagemode; ///< ``MS_IMAGEMODE_*`` value - see :ref:`IMAGEMODE <mapfile-outputformat-imagemode>`
+    int  renderer;  ///< A :ref:`render mode constant<mapfile-constants-render>` - normally set internally based on the driver and some other setting in the constructor.
+    int  imagemode; ///< An :ref:`Image mode constant<mapfile-constants-imagemode>` - see :ref:`IMAGEMODE <mapfile-outputformat-imagemode>`
     int  transparent; ///< See :ref:`TRANSPARENT <mapfile-outputformat-transparent>`
     int  bands; ///< The number of bands in the raster, normally set via the BAND_COUNT formatoption - this field should be considered read-only
                 ///< Only used for the "raw" modes, MS_IMAGEMODE_BYTE, MS_IMAGEMODE_INT16, and MS_IMAGEMODE_FLOAT32
@@ -1014,8 +1014,8 @@ The :ref:`STYLE <style>` object. An instance of styleObj is associated with one
     %immutable;
 #endif /* SWIG */
 
-    int refcount;
-    char *symbolname; ///< Name of the style's symbol - see :ref:`symbolname <mapfile-style-symbolname>`
+    int refcount; ///< number of references to this object
+    char *symbolname; ///< Name of the style's symbol - see :ref:`symbolname <mapfile-style-symbol>`
 
 #ifdef SWIG
     %mutable;
@@ -1076,13 +1076,13 @@ The :ref:`STYLE <style>` object. An instance of styleObj is associated with one
 
     double offsetx; ///< Draw with pen or symbol offset from map data, for shadows, hollow symbols, etc - see :ref:`OFFSET <mapfile-style-offset>`
     double offsety; ///< Draw with pen or symbol offset from map data, for shadows, hollow symbols, etc - see :ref:`OFFSET <mapfile-style-offset>`
-    double polaroffsetpixel; ///< Specifies the radius/distance - see :ref:`POLAROFFSET <mapfile-style-polaroff>`
-    double polaroffsetangle; ///< Specified the angle - see :ref:`POLAROFFSET <mapfile-style-polaroff>`
+    double polaroffsetpixel; ///< Specifies the radius/distance - see :ref:`POLAROFFSET <mapfile-style-polaroffset>`
+    double polaroffsetangle; ///< Specified the angle - see :ref:`POLAROFFSET <mapfile-style-polaroffset>`
 
 
     double minscaledenom; ///< See :ref:`MINSCALEDENOM <mapfile-style-minscaledenom>`
     double maxscaledenom; ///< See :ref:`MAXSCALEDENOM <mapfile-style-maxscaledenom>`
-    int sizeunits; ///< See :ref:`SIZEUNITS <mapfile-style-sizeunits>` - supersedes class's sizeunits
+    int sizeunits; ///< Supersedes class's :ref:`SIZEUNITS <mapfile-class-sizeunits>` to allow fine-grained sizing for improved SLD (RFC 124)
   };
 
 #define MS_STYLE_SINGLE_SIDED_OFFSET -99
@@ -1409,12 +1409,6 @@ typedef struct labelObj labelObj;
 #ifdef SWIG
     %mutable;
 #endif /* SWIG */
-
-    /* TODO: remove for 6.0, confirm with Assefa  - unused in codebase
-    Used to force the result retrieving to use getshape instead of resultgetshape
-    */
-    int usegetshape; ///< \**TODO** Unused - remove
-
   } resultCacheObj;
 
 
@@ -1651,16 +1645,22 @@ The :ref:`REFERENCE <reference>` object
   /*      base unit of a map.                                             */
   /************************************************************************/
 
+  /**
+  An individual value within the :ref:`SCALETOKEN <mapfile-layer-scaletoken>` object
+  */
   typedef struct {
-    double minscale;
-    double maxscale;
-    char *value;
+    double minscale; ///< The minimum scale for the replacement
+    double maxscale; ///< The maximum scale for the replacement
+    char *value; ///< The token replacement value
   } scaleTokenEntryObj;
 
+  /**
+  The :ref:`SCALETOKEN <mapfile-layer-scaletoken>` object
+  */
   typedef struct {
-     char *name;
-     int n_entries;
-     scaleTokenEntryObj *tokens;
+     char *name; ///< The name of the token to replace in the :ref:`DATA <mapfile-layer-data>` statement
+     int n_entries; ///< The number of values within the scaletoken
+     scaleTokenEntryObj *tokens; ///< A reference to the values
   } scaleTokenObj;
 
 #ifndef SWIG
@@ -2015,11 +2015,18 @@ void msPopulateTextSymbolForLabelAndString(textSymbolObj *ts, labelObj *l, char
 #endif /*SWIG*/
 
   /* Function prototypes, wrapable */
-  MS_DLL_EXPORT int msSaveImage(mapObj *map, imageObj *img, const char *filename);
-  MS_DLL_EXPORT void msFreeImage(imageObj *img);
-  MS_DLL_EXPORT int msSetup(void);
-  MS_DLL_EXPORT void msCleanup(void);
-  MS_DLL_EXPORT mapObj *msLoadMapFromString(char *buffer, char *new_mappath);
+  MS_DLL_EXPORT int msSaveImage(mapObj *map, imageObj *img, const char *filename); ///< Saves a map image to a file
+
+  MS_DLL_EXPORT void msFreeImage(imageObj *img); ///< Generic function to free a imageObj
+
+  MS_DLL_EXPORT int msSetup(void); ///< Sets up threads and font cache - called when MapScript is initialised
+
+  MS_DLL_EXPORT void msCleanup(void); ///< Attempts to recover all dynamically allocated resources allocated by MapServer code and 
+                                      ///<  dependent libraries. It it used primarily for final clean-up in scripts that need to do 
+                                      ///< memory leak testing to get rid of "noise" one-time allocations. 
+                                      ///< It should not normally be used by production code.
+
+  MS_DLL_EXPORT mapObj *msLoadMapFromString(char *buffer, char *new_mappath); ///< Sets up string-based mapfile loading and calls loadMapInternal to do the work
 
   /* Function prototypes, not wrapable */