minor java mapscript function signature discrepancies wrt doc

[richf]

This is in mapserver 5.0.0, comparing mapscript/doc/mapscript.txt to the actual java mapscript implementation at mapscript/java/edu/umn/gis/mapscript/*.java

They're all pretty minor. I don't know if the problem is that the doc needs updating or the code does. It's quite possible there are more such discrepancies, these are just the ones I have come across.

1) The doc for mapobj.setExtent() claims:

setExtent( float minx, float miny, float miny, float maxy ) : int

Set the map extent, returns MS_SUCCESS or MS_FAILURE.

However, in the java mapscript source, it returns void:

public void setExtent(rectObj extent)

2) The doc for the constructor of pointObj claims:

new pointObj( [ float x=0.0, float y=0.0, float z=0.0, float m=-2e38 ] ) : pointObj

Create new instance. Easting, northing, and measure arguments are optional.

I'm not entirely sure what that means -- are easting, northing, and measure x, y, and m respectively? Meaning only z is required?

From the java mapscript source, there are two possible constructors, and all of x, y, and z are required:

public pointObj(double x, double y, double z, double m) public pointObj(double x, double y, double z)

3) The doc for the constructor of rectObj also makes claims about optional

args:

new rectObj( [ float minx=-1.0, float miny=-1.0, float maxx=-1.0, float maxy=-1.0, int imageunits=MS_FALSE ] ) : rectObj

Create new instance. The four easting and northing arguments are optional and default to -1.0. Note the new optional fifth argument which allows creation of rectangles in image (pixel/line) units which are also tested for validity.

But in the java mapscript source, there is only a single constructor, and all arguments are required:

public rectObj(double minx, double miny, double maxx, double maxy, int imageunits)

4) In "Documentation Elements", the claim is made:

To make the document as agnostic as possible, we refer to the following types: int, float, and string. There are yet no mapscript methods that return arrays or sequences or accept array or sequence arguments.

That's I think a little misleading. See forexample imageObj.getBytes(), which returns a byte[] array in java, and mapObj.getLayersDrawingOrder(), which returns an intarray.

5) The following methods that exist in the java mapscript code are all missing

from the doc:

mapObj.setWidth() mapObj.setHeight() mapObj.getNumlayers() layerObj.getName() layerObj.setConnection() layerObj.getData() layerObj.setData() layerObj.getLabelitem() layerObj.getNumclasses() layerObj.getLabel() labelObj.getPartials() [actually, the doc claims there are labelObj.setPartials() "None" labelObj Methods] [there is no mention of delete() for any class]

[richf]

(sorry for some of the bad formatting in the original post)

oh, duh, i see that the doc don't actually claim to be for 5.0.0:

=============================================================================
 Mapscript Variables
=============================================================================

-----------------------------------------------------------------------------
 Version
-----------------------------------------------------------------------------

=====================  ============  ===========
 Name                     Type         Value   
---------------------  ------------  -----------
  MS_VERSION            character       4.8
=====================  ============  ===========

so maybe this is all just part of a larger, already known issue, that the mapscript doc needs updating.

[unicoletti]

Closing it due to its age and because it's not only a Java issue as the docs are shared among all mapscript interfaces.