Initial commit

Implementing-formats-with-`ol.format.Format`.md

@@ -0,0 +1,15 @@
+`ol.format.Format` defines a number of abstract methods including:
+
+* `readFeatures` returning an `Array.<ol.Feature>`
+* `readFeature` returning an `ol.Feature`
+* `readGeometry` returning an `ol.geom.Geometry`
+
+Having different functions for multiple return types allows both the user to specify what type of data he wants and for the Compiler to properly type check the code. Depending on the format, it is entirely reasonable to leave one or more of these methods unimplemented, or provide sensible default implementations.
+
+For example, `ol.format.GPX` only supports reading multiple features.  Therefore `readFeature` and `readGeometry` are unimplemented and will raise an exception if called.
+
+The IGC format contains only one feature per file, so `readFeature` returns that feature, `readFeatures` returns an array containing a single feature which is the feature in the file, and `readGeometry` is unimplemented.
+
+For formats that only contain a single geometry, like WKB and WKT, `readGeometry` should return that geometry, `readFeature` should return a feature with its geometry set to the geometry read from the file, and `readFeatures` should return an array containing the single feature returned by `readFeature`.
+
+If a file cannot be parsed, then the return value should be `null` for all three cases. Parsing failures should not raise exceptions (although exceptions can be used internally).