Opened 15 years ago

Closed 12 years ago

#2532 closed defect (wontfix)

minor java mapscript function signature discrepancies wrt doc

Reported by: richf Owned by: unicoletti
Priority: low Milestone:
Component: MapScript-Java Version: 5.0
Severity: minor Keywords:


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


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]

Change History (3)

comment:1 by richf, 15 years ago

(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


=====================  ============  ===========
 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.

comment:2 by sdlime, 14 years ago

Component: MapScriptMapScript-Java
Owner: changed from sdlime to unicoletti

comment:3 by unicoletti, 12 years ago

Resolution: wontfix
Status: newclosed

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

Note: See TracTickets for help on using tickets.