[OpenLayers-Dev] constructor signatures

[Tim Schaub]

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

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.

> It will be difficult to keep the arguments up to date for the class
> you inherit from, but maybe it is enough to just document the options
> specific for this class, and link to the inherited options "class"
> somehow. I'm not very familiar with NaturalDocs, so I don't know if
> "Class" is the best keyword for the options object, but I like it
> better than some of the docs today (see RootContainer's constructor).
> This is similar to what Google Maps does in their documentation:
> http://code.google.com/apis/maps/documentation/javascript/reference.html#MapTypeControlOptions
> 
> Options objects can have required properties. Just throw an Error if
> it's missing. Maybe a required options array on the prototype, so it
> can be done in a generic manner.
> 
> Errors thrown from a minified script is quite useless, since it
> doesn't say anything about class name or line number in original
> source. Maybe it's time to integrate a simple logging framework? Can
> start a separate thread to discuss this.
> 
> 
> Best regards,
> Gregers
> _______________________________________________
> Dev mailing list
> Dev at openlayers.org
> http://openlayers.org/mailman/listinfo/dev


-- 
Tim Schaub
OpenGeo - http://opengeo.org
Expert service straight from the developers.