Document imageObj and hashTableObj (#6168)

maphash.h

@@ -54,14 +54,19 @@ extern "C" {
   };
 #endif /*SWIG*/
 
+
+/**
+ * An object to store key-value pairs
+ *
+ */
   typedef struct {
 #ifndef SWIG
     struct hashObj **items;  /* the hash table */
 #endif
 #ifdef SWIG
     %immutable;
 #endif /*SWIG*/
-    int              numitems;  /* number of items */
+    int              numitems;  ///< \**immutable** number of items
 #ifdef SWIG
     %mutable;
 #endif /*SWIG*/

mapscript/python/pyextend.i

@@ -322,13 +322,11 @@ def fromstring(data, mappath=None):
 
 %extend imageObj {
 
-    /* ======================================================================
-       write()
-
-       Write image data to an open Python file or file-like object.
-       Overrides extension method in mapscript/swiginc/image.i.
-       Intended to replace saveToString.
-    ====================================================================== */
+    /**
+    Write image data to an open file handle. Intended to replace
+    saveToString.  See ``python/pyextend.i`` for the Python specific
+    version of this method.
+    */
     int write( PyObject *file=Py_None )
     {
         unsigned char *imgbuffer=NULL;
@@ -375,7 +373,9 @@ def fromstring(data, mappath=None):
         return retval;
     }
 
-    /* Deprecated */  
+    /**
+    \**Deprecated** - replaced by the :func:`imageObj.write` method
+    */
     PyObject *saveToString() {
         int size=0;
         unsigned char *imgbytes;
@@ -458,6 +458,10 @@ pattern = property(pattern_get, pattern_set, doc=r"""pattern : list **Python Onl
         return self.numitems
 
     def keys(self):
+        """
+        **Python-only**. In Python MapScript the ``hashTableObj`` can be used and accessed
+        as a dictionary. The ``keys`` method returns a view of all the keys in the ``hashTableObj``.
+        """
 
         keys = []
         k = None

mapscript/swiginc/image.i

@@ -107,12 +107,12 @@
         msSaveImage(map, self, filename );
     }
 
+#ifndef SWIGPYTHON
     /**
     Write image data to an open file handle. Intended to replace
-    saveToString.  See python/pyextend.i for the Python specific
+    saveToString.  See ``python/pyextend.i`` for the Python specific
     version of this method.
     */
-#ifndef SWIGPYTHON
     int write( FILE *file=NULL )
     {
         int retval=MS_FAILURE;

mapserver.h

@@ -1525,30 +1525,33 @@ typedef struct labelObj labelObj;
 
   /************************************************************************/
   /*                               imageObj                               */
-  /*                                                                      */
-  /*      A wrapper for GD and other images.                              */
   /************************************************************************/
+
+/**
+ * An image object is a wrapper for images generated by MapServer. 
+ *
+ */
   struct imageObj{
 #ifdef SWIG
     %immutable;
 #endif
-    int width, height;
-    double resolution;
-    double resolutionfactor;
+    int width; ///< \**immutable** image width in pixels
+    int height; ///< \**immutable** image height in pixels
+    double resolution; ///< \**immutable** image resolution in pixels per inch
+    double resolutionfactor; ///< \**immutable** resolution factor
 
-    char *imagepath, *imageurl;
+    char *imagepath; ///< \**immutable** if image is drawn by :func:`mapObj.draw` this is :ref:`IMAGEPATH <mapfile-web-imagepath>`
+    char *imageurl; ///< \**immutable** if image is drawn by :func:`mapObj.draw` this is :ref:`IMAGEURL <mapfile-web-imageurl>`
+    outputFormatObj *format; ///< \**immutable** an :class:`outputFormatObj` representing the output format of the image
 
-    outputFormatObj *format;
 #ifndef SWIG
     tileCacheObj *tilecache;
     int ntiles;
+    int size;
 #endif
 #ifdef SWIG
     %mutable;
 #endif
-#ifndef SWIG
-    int size;
-#endif
 
 #ifndef SWIG
     union {