[OpenLayers-Dev] constructor signatures

[christopher.schmidt at nokia.com]

On Jun 18, 2010, at 11:23 AM, ext Tim Schaub wrote:

> Gregers Gram Rygg wrote:
>> How about max 3 arguments for any constructor or method in 3.0? Need
>> more arguments, use an options object.
>> 
>> The only downside I see with options objects are that it gets more
>> difficult to read the source code to see what the available options
>> are. One approach to solve this would be to use fake option classes
>> for Natural Docs.
>>  * options - {GridLayerOptions} Hashtable of extra options to tag
>> onto the layer
>> 
>> Then document the GridLayerOptions in the same file (bottom?):
>> /**
>>  * Class: GridLayerOptions
>>  * Inherits: <LayerOptions>
>>  *
>>  * Properties:
>>  * name - {String} *required*
>>  * url - {String} *required*
>>  * params - {Object} *required*
>>  * .....
>>  */
>> 
> 
> I totally agree that we need to improve things on the documentation 
> side.  We'll need to settle on some documentation conventions to make 
> things easier.
> 
> Given our current setup, compare how I documented the WMTS constructor 
> to how the WMS constructor is documented.
> 
> WMTS:
> http://dev.openlayers.org/apidocs/files/OpenLayers/Layer/WMTS-js.html#OpenLayers.Layer.WMTS.OpenLayers.Layer.WMTS
> 
> WMS:
> http://dev.openlayers.org/apidocs/files/OpenLayers/Layer/WMS-js.html#OpenLayers.Layer.WMS.OpenLayers.Layer.WMS
> 
> If I didn't know already, I'd find it very hard to figure out that the 
> "layers" param is required for the WMS layer to work.

I regularly use a WMS server with no 'layers' param. I know that this
is a special case, but the layer does not technically require this 
parameter to work. (Your server might; the spec might even, but 
the parameters that are required depend on your server.)


>  The same goes for 
> the TMS layer and others that followed this convention of having 
> strictly required properties buried as properties of an object that is 
> the second or third argument to the constructor.

TMS is broken. The XYZ/OSM layer is a better example of how I try to do 
things now; TMS was simply a mistake from day one, and I didn't realize
it until after we'd already released :)

> Granted, the issue above is strictly a documentation one.  And we could 
> (really should) go with lists of lists for these multiple argument 
> constructors that have required properties in the second or third 
> arguments.  But I think our documentation challenge will be easier with 
> a single argument constructor.

I don't think that documenting params is any easier with a single
argument constructor, personally. 

Regards,
-- 
Christopher Schmidt
Nokia