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
_______________________________________________
Dev mailing list
Dev@openlayers.org
http://openlayers.org/mailman/listinfo/dev
