Skip to content

Commit

Permalink
Add docstrings to SWIG objects (#5930)
Browse files Browse the repository at this point in the history 
* Add docstrings to the classObj

* Add clsuter, color, connpool, dbfinfo, error, hashtable, image docstrings

* Revert to UNIX EOL
  • Loading branch information
@geographika
geographika committed Nov 26, 2019
1 parent 528f36d commit b85122d
Show file tree
Hide file tree
Showing 8 changed files with 179 additions and 76 deletions.
78 changes: 65 additions & 13 deletions mapscript/swiginc/class.i
View file
@@ -1,13 +1,12 @@
/* ===========================================================================
$Id$
Project: MapServer
Purpose: SWIG interface file for mapscript classObj extensions
Author: Steve Lime
Sean Gillies, sgillies@frii.com
Seth Girvin
===========================================================================
Copyright (c) 1996-2001 Regents of the University of Minnesota.
Copyright (c) 1996-2019 Regents of the University of Minnesota.
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
Expand All @@ -31,6 +30,13 @@

%extend classObj {

// manually add parameter here or get mapscript.mapscript.layerObj in output docs
%feature("autodoc", "classObj.__init__(layerObj layer=None)
Create a new child classObj instance at the tail (highest index) of the
class array of the parent_layer. A class can be created outside the
context of a parent layer by omitting the layerObj constructor argument") classObj;

classObj(layerObj *layer=NULL)
{
classObj *new_class=NULL;
Expand All @@ -56,7 +62,7 @@
if (initClass(layer->class[layer->numclasses]) == -1)
return NULL;
layer->class[layer->numclasses]->layer = layer;
MS_REFCNT_INCR(layer->class[layer->numclasses]);
MS_REFCNT_INCR(layer->class[layer->numclasses]);
layer->numclasses++;
return (layer->class[layer->numclasses-1]);
}
Expand All @@ -69,17 +75,21 @@
if (self)
{
if (freeClass(self)==MS_SUCCESS) {
free(self);
self=NULL;
}
free(self);
self=NULL;
}
}
}

%feature("docstring") updateFromString
"Update a class from a string snippet. Returns :data:`MS_SUCCESS` or :data:`MS_FAILURE`";
int updateFromString(char *snippet)
{
return msUpdateClassFromString(self, snippet, MS_FALSE);
}


%feature("docstring") convertToString
"Output the CLASS as a Mapfile string"
%newobject convertToString;
char* convertToString()
{
Expand All @@ -90,6 +100,8 @@
%newobject cloneClass;
classObj *cloneClass()
#else
%feature("docstring") clone
"Return an independent copy of the class without a parent layer"
%newobject clone;
classObj *clone()
#endif
Expand Down Expand Up @@ -121,6 +133,9 @@
return new_class;
}

%feature("docstring") setExpression
"Set :mapfile:`EXPRESSION <class.html#index-4>` string where `expression` is a MapServer regular, logical or string expression.
Returns :data:`MS_SUCCESS` or :data:`MS_FAILURE`";
int setExpression(char *expression)
{
if (!expression || strlen(expression) == 0) {
Expand All @@ -130,24 +145,33 @@
else return msLoadExpressionString(&self->expression, expression);
}

%feature("docstring") getExpressionString
"Return a string representation of the :mapfile:`EXPRESSION <class.html#index-4>` enclosed in the quote characters appropriate to the expression type";
%newobject getExpressionString;
char *getExpressionString() {
return msGetExpressionString(&(self->expression));
}

%feature("docstring") setText
"Set :mapfile:`TEXT <class.html#index-22>` string where `text` is a MapServer text expression.
Returns :data:`MS_SUCCESS` or :data:`MS_FAILURE`";
int setText(char *text) {
if (!text || strlen(text) == 0) {
msFreeExpression(&self->text);
return MS_SUCCESS;
}
}
else return msLoadExpressionString(&self->text, text);
}

%feature("docstring") getTextString
"Return a string representation of :mapfile:`TEXT <class.html#index-22>`";
%newobject getTextString;
char *getTextString() {
return msGetExpressionString(&(self->text));
}

%feature("docstring") getMetaData
"**To be removed in 8.0** - use the metadata property";
char *getMetaData(char *name) {
char *value = NULL;
if (!name) {
Expand All @@ -162,20 +186,28 @@
return value;
}

%feature("docstring") setMetaData
"**To be removed in 8.0** - use the metadata property";
int setMetaData(char *name, char *value) {
if (msInsertHashTable(&(self->metadata), name, value) == NULL)
return MS_FAILURE;
return MS_SUCCESS;
}

%feature("docstring") getFirstMetaDataKey
"**To be removed in 8.0** - use the metadata property";
char *getFirstMetaDataKey() {
return (char *) msFirstKeyFromHashTable(&(self->metadata));
}


%feature("docstring") getNextMetaDataKey
"**To be removed in 8.0** - use the metadata property";
char *getNextMetaDataKey(char *lastkey) {
return (char *) msNextKeyFromHashTable(&(self->metadata), lastkey);
}


%feature("docstring") drawLegendIcon
"Draw the legend icon onto *image* at *dstx*, *dsty*. Returns :data:`MS_SUCCESS` or :data:`MS_FAILURE`";
int drawLegendIcon(mapObj *map, layerObj *layer, int width, int height, imageObj *dstImage, int dstX, int dstY) {
if(layer->sizeunits != MS_PIXELS) {
map->cellsize = msAdjustExtent(&(map->extent), map->width, map->height);
Expand All @@ -186,12 +218,16 @@

return msDrawLegendIcon(map, layer, self, width, height, dstImage, dstX, dstY, MS_TRUE, NULL);
}


%feature("docstring") createLegendIcon
"Draw and return a new legend icon";
%newobject createLegendIcon;
imageObj *createLegendIcon(mapObj *map, layerObj *layer, int width, int height) {
return msCreateLegendIcon(map, layer, self, width, height, MS_TRUE);
}

%feature("docstring") getLabel
"Return a reference to the :class:`labelObj` at *index* in the labels array";
%newobject getLabel;
labelObj *getLabel(int i) {
if (i >= 0 && i < self->numlabels) {
Expand All @@ -206,13 +242,18 @@
#ifdef SWIGCSHARP
%apply SWIGTYPE *SETREFERENCE {labelObj *label};
#endif
%feature("docstring") addLabel
"Add a :class:`labelObj` to the :class:`classObj` and return its index in the labels array";
int addLabel(labelObj *label) {
return msAddLabelToClass(self, label);
}
#ifdef SWIGCSHARP
%clear labelObj *label;
#endif

%feature("docstring") removeLabel
"Remove the :class:`labelObj` at *index* from the labels array and return a
reference to the :class:`labelObj`. numlabels is decremented, and the array is updated";
%newobject removeLabel;
labelObj *removeLabel(int index) {
labelObj* label = (labelObj *) msRemoveLabelFromClass(self, index);
Expand All @@ -221,6 +262,8 @@
}

/* See Bugzilla issue 548 for more details about the *Style methods */
%feature("docstring") getStyle
"Return a reference to the :class:`styleObj` at *index* in the styles array";
%newobject getStyle;
styleObj *getStyle(int i) {
if (i >= 0 && i < self->numstyles) {
Expand All @@ -235,24 +278,33 @@
#ifdef SWIGCSHARP
%apply SWIGTYPE *SETREFERENCE {styleObj *style};
#endif
%feature("docstring") insertStyle
"Insert a **copy** of *style* into the styles array at index *index*.
Default is -1, or the end of the array. Returns the index at which the style was inserted.";
int insertStyle(styleObj *style, int index=-1) {
return msInsertStyle(self, style, index);
}
#ifdef SWIGCSHARP
%clear styleObj *style;
#endif

%feature("docstring") removeStyle
"Remove the :class:`styleObj` at *index* from the styles array and return a copy.";
%newobject removeStyle;
styleObj *removeStyle(int index) {
styleObj* style = (styleObj *) msRemoveStyle(self, index);
if (style) MS_REFCNT_INCR(style);
return style;
}

%feature("docstring") moveStyleUp
"Swap the :class:`styleObj` at *index* with the styleObj at *index* - 1";
int moveStyleUp(int index) {
return msMoveStyleUp(self, index);
}

%feature("docstring") moveStyleDown
"Swap the :class:`styleObj` at *index* with the :class:`styleObj` at *index* + 1";
int moveStyleDown(int index) {
return msMoveStyleDown(self, index);
}
Expand Down
27 changes: 20 additions & 7 deletions mapscript/swiginc/cluster.i
View file
@@ -1,12 +1,10 @@
/* ===========================================================================
$Id$
Project: MapServer
Purpose: SWIG interface file for mapscript clusterObj extensions
Author: Tamas Szekeres
Seth Girvin
===========================================================================
Copyright (c) 1996-2007 Regents of the University of Minnesota.
Copyright (c) 1996-2019 Regents of the University of Minnesota.
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
Expand All @@ -30,17 +28,25 @@

%extend clusterObj
{

%feature("docstring") updateFromString
"Update a cluster from a string snippet. Returns :data:`MS_SUCCESS` or :data:`MS_FAILURE`";
int updateFromString(char *snippet)
{
return msUpdateClusterFromString(self, snippet);
}


%feature("docstring") convertToString
"Output the CLUSTER as a Mapfile string"
%newobject convertToString;
char* convertToString()
{
return msWriteClusterToString(self);
}


%feature("docstring") setGroup
"Set :mapfile:`GROUP <cluster.html#index-5>` string where `group` is a MapServer text expression.
Returns :data:`MS_SUCCESS` or :data:`MS_FAILURE`";
int setGroup(char *group)
{
if (!group || strlen(group) == 0) {
Expand All @@ -50,19 +56,26 @@
else return msLoadExpressionString(&self->group, group);
}

%feature("docstring") getGroupString
"Return a string representation of :mapfile:`GROUP <cluster.html#index-5>`";
%newobject getGroupString;
char *getGroupString() {
return msGetExpressionString(&(self->group));
}

%feature("docstring") setFilter
"Set :mapfile:`FILTER <cluster.html#index-6>` string where `filter` is a MapServer text expression.
Returns :data:`MS_SUCCESS` or :data:`MS_FAILURE`";
int setFilter(char *filter) {
if (!filter || strlen(filter) == 0) {
msFreeExpression(&self->filter);
return MS_SUCCESS;
}
}
else return msLoadExpressionString(&self->filter, filter);
}

%feature("docstring") getFilterString
"Return a string representation of :mapfile:`FILTER <cluster.html#index-6>`";
%newobject getFilterString;
char *getFilterString() {
return msGetExpressionString(&(self->filter));
Expand Down
39 changes: 24 additions & 15 deletions mapscript/swiginc/color.i
View file
@@ -1,13 +1,12 @@
/* ===========================================================================
$Id$
Project: MapServer
Purpose: SWIG interface file for mapscript colorObj extensions
Author: Steve Lime
Sean Gillies, sgillies@frii.com
Seth Girvin
===========================================================================
Copyright (c) 1996-2001 Regents of the University of Minnesota.
Copyright (c) 1996-2019 Regents of the University of Minnesota.
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
Expand All @@ -29,13 +28,12 @@
===========================================================================
*/

%{
#include "../../mapserver.h"
%}

%extend colorObj
{


%feature("autodoc", "colorObj.__init__()
Create a new instance. The color arguments are optional.") colorObj;
colorObj(int red=0, int green=0, int blue=0, int alpha=255)
{
colorObj *color;
Expand All @@ -53,14 +51,16 @@

MS_INIT_COLOR(*color, red, green, blue, alpha);

return(color);
return(color);
}

~colorObj()
{
free(self);
}


%feature("docstring") setRGB
"Set all four RGBA components. Returns :data:`MS_SUCCESS` or :data:`MS_FAILURE`";
int setRGB(int red, int green, int blue, int alpha = 255)
{
/* Check colors */
Expand All @@ -72,7 +72,14 @@
MS_INIT_COLOR(*self, red, green, blue, alpha);
return MS_SUCCESS;
}


%feature("docstring") setHex
"Set the color to values specified in case-independent hexadecimal notation.
hex must start with a '#' followed by three or four hex bytes, e.g. '#ffffff'
or '#ffffffff'. If only three hex bytes are supplied, the alpha will be set
to 255. Calling setHex('#ffffff') therefore assigns values of 255 to each
color component, including the alpha.
Returns :data:`MS_SUCCESS` or :data:`MS_FAILURE`";
int setHex(char *psHexColor)
{
int red, green, blue, alpha = 255;
Expand All @@ -96,7 +103,11 @@
return MS_FAILURE;
}
}


%feature("docstring") toHex
"Complement to setHex, returning a hexadecimal representation of the color
components. If alpha is 255 then this is three hex bytes '#rrggbb',
otherwise four hex bytes '#rrggbbaa'";
%newobject toHex;
char *toHex()
{
Expand Down Expand Up @@ -129,6 +140,4 @@
}
return hexcolor;
}

}

0 comments on commit b85122d

Please sign in to comment.