Differentiating doc from apidoc

This renames the doc task to apidoc.  The apidoc delegates to jsdoc3 currently.  We will have additional documentation that is not built by jsdoc3.  It makes sense to reserve the more general 'doc' name for building all documentation (not just apidoc).

apidoc/conf.json

@@ -1,8 +1,7 @@
 {
     "opts": {
         "recurse": true,
-        "template": "doc/template",
-        "tutorials": "doc/tutorials"
+        "template": "apidoc/template"
     },
     "tags": {
         "allowUnknownTags": true
@@ -13,8 +12,8 @@
     },
     "plugins": [
         "plugins/markdown",
-        "doc/plugins/inheritdoc",
-        "doc/plugins/exports"
+        "apidoc/plugins/inheritdoc",
+        "apidoc/plugins/exports"
     ],
     "markdown": {
         "parser": "gfm"

build.py

@@ -167,7 +167,7 @@ virtual('default', 'build')
 
 
 virtual('integration-test', 'lint', 'build', 'build-all',
-        'test', 'build-examples', 'check-examples', 'doc')
+        'test', 'build-examples', 'check-examples', 'apidoc')
 
 
 virtual('build', 'build/ol.css', 'build/ol.js',
@@ -591,14 +591,14 @@ def plovr_jar(t):
     t.info('downloaded %r', t.name)
 
 
-virtual('doc', 'build/jsdoc-%(BRANCH)s-timestamp' % vars(variables))
+virtual('apidoc', 'build/jsdoc-%(BRANCH)s-timestamp' % vars(variables))
 
 
 @target('build/jsdoc-%(BRANCH)s-timestamp' % vars(variables), 'host-resources',
         'build/src/external/src/exports.js', 'build/src/external/src/types.js',
-        SRC, SHADER_SRC, ifind('doc/template'))
+        SRC, SHADER_SRC, ifind('apidoc/template'))
 def jsdoc_BRANCH_timestamp(t):
-    t.run('%(JSDOC)s', '-c', 'doc/conf.json', 'src', 'doc/index.md',
+    t.run('%(JSDOC)s', '-c', 'apidoc/conf.json', 'src', 'apidoc/index.md',
           '-d', 'build/hosted/%(BRANCH)s/apidoc')
     t.touch()
 
@@ -780,11 +780,11 @@ The most common targets are:
   help             - Shows this help.
 
 Other less frequently used targets are:
-  doc              - Builds the API-Documentation using JSDoc3.
+  apidoc           - Builds the API-Documentation using JSDoc3.
   integration-test - Builds all examples in various modes and usually tales a
                      long time to finish. This target calls the following
                      targets: lint, build, build-all, test, build-examples,
-                     check-examples and doc.
+                     check-examples and apidoc.
   reallyclean      - Remove untracked files from the repository.
   checkdeps        - Checks whether all required development software is
                      installed on your machine.

doc/tutorials/ol3.json

@@ -1,3 +0,0 @@
-{
-    "title": "OpenLayers 3 Architecture"
-}

doc/tutorials/ol3.md

@@ -1,274 +0,0 @@
-CLASS HIERARCHY
-===============
-
-```
-goog.math.Coordinate  // Simple 2D point
-|
-+- TileCoord
-
-goog.math.Box
-|
-+- Extent // The extent of a single object in two dimensions, projection not stored
-|
-+- TileBounds  // A range of tiles in two dimensions, integer coordinates, z not stored
-
-
-Projection
-
-
-goog.events.EventTarget
-|
-+- MVCObject
-|  |
-|  +- Camera
-|  |
-|  +- Control
-|  |  |
-|  |  +- ?
-|  |
-|  +- Layer
-|  |  |
-|  |  +- TileLayer
-|  |  |  |
-|  |  |  +- TMSTileLayer
-|  |  |  |
-|  |  |  +- WMTSTileLayer
-|  |  |  |
-|  |  |  +- XYZTileLayer / OSMTileLayer
-|  |  |
-|  |  +- VectorLayer
-|  |  |
-|  |  +- ImageLayer
-|  |
-|  +- LayerRenderer
-|  |
-|  +- LayerRendererOptions
-|  |
-|  +- Map
-|  |
-|  +- MapRenderer
-|  |  |
-|  |  +- HTMLMapRenderer
-|  |  |
-|  |  +- WebGLMapRenderer
-|  |
-|  +- MVCArray
-|  |  |
-|  |  +- ControlArray
-|  |  |
-|  |  +- LayerViewArray
-|
-|  +- TileQueue
-|
-+- Tile
-```
-
-
-Layer renderer hierarchy
-------------------------
-
-```
-goog.events.EventTarget
-|
-+- MVCObject
-   |
-   +- LayerRenderer
-      |
-      +- SingleTileLayerRenderer
-      |  |
-      |  +- HTMLSingleTileLayerRenderer
-      |  |
-      |  +- WebGLSingleTileLayerRenderer
-      |
-      +- TileLayerRenderer
-      |  |
-      |  +- HTMLTileLayerRenderer
-      |  |
-      |  +- WebGLTileLayerRenderer
-      |
-      +- VectorLayerRenderer
-      |  |
-      |  +- HTMLVectorLayerRenderer
-      |  |  |
-      |  |  +- SVGHTMLVectorLayerRenderer
-      |  |  |
-      |  |  +- Canvas2DHTMLVectorLayerRenderer
-      |  |  |
-      |  |  +- VMLHTMLVectorLayerRenderer
-      |  |
-      |  +- WebGLVectorLayerRenderer
-```
-
-
-OBJECT PROPERTIES AND METHODS
-=============================
-
-Notation:
-
-- `property type`  property with type, trailing ? indicates unsure, getters and setters are assumed to exist.
-- `f(args) -> type`  function taking args returning type.
-- `f(args) -> type = something`  f is a trivial wrapper around something.
-- `fires 'x'`  fires events of type 'x'.
-
-Principles:
-
-- All non-trivial objects inherit from `MVCObject`.
-- All non-trivial collections are either `MVCArrays` or a child class thereof.
-- Resolutions are `Array.<number>`, infinitely scalable resources (e.g. vectore layers) have resolutions == null.
-
-```
-MVCObject
-  as Google Maps MVCObject
-  freeze()
-  unfreeze()
-
-TileCoord
-  clone() -> TileCoord
-  getHash() -> number
-
-TileBounds
-  forEachTileCoord(z, function(tileCoord))
-
-Tile
-  tileCoord TileCoord
-  url string
-  state UNLOADED | LOADING | LOADED
-  fires 'loaded' // when loaded
-  fires 'aborted'  // when loading is aborted
-
-Camera
-   position goog.math.Coordinate
-   resolution number
-   rotation number
-
-Layer
-   projections Array.<Projection>
-   extent Extent
-   getResolutions() -> Array.<number>|null
-   fires 'change' // when data changes
-
-LayerArray
-   getResolutions() -> Array.<number>|null
-   getMaxResolution() = this.getResolutions()[0] | null
-
-LayerRendererOptions
-   layer Layer
-   visible boolean
-   opacity number
-   brightness number
-   color number
-   hue number
-   saturation number
-
-Map
-   projection Projection
-   renderer Renderer
-   layers LayerArray
-   addLayer(layer) = layers.push(layer)
-   getExtent() -> Extent
-   getMaxResolution() = layers.getMaxResolution()
-
-TileGrid
-   resolutions Array.<number>
-   extent ol.Extent
-   xEast boolean
-   ySouth boolean
-   origin(s) Coord|Array.<Coord>
-   tileSize goog.math.Size
-   forEachTileCoordChild(tileCoord, function(z, TileBounds))
-   forEachTileCoordParent(tileCoord, function(z, TileBounds))
-   getExtentTileBounds(z, extent) -> TileBounds
-   getTileCoord(coordinate) -> TileCoord
-   getTileCoordCenter(tileCoord) -> goog.math.Coordinate
-   getTileCoordExtent(tileCoord) -> ol.Extent
-   getTileCoordResolution(tileCoord) -> number
-   getZForResolution(resolution) -> number
-
-TileLayer
-   tileGrid TileGrid
-   tileUrl function(tileCoord) -> string
-   getTileCoordUrl(tileCoord) -> string = this.tileUrl(tileCoord)
-
-TileQueue
-   camera Camera  // or maybe MVCArray.<Camera> ?
-   getTileCoordPriority(tileCoord) -> number  // private
-   enqueueTile(Tile)
-
-VectorLayer
-   forEachFeature(resolution, extent, projection, function(Feature))
-
-Renderer
-   target HTMLDivElement
-   map Map
-   camera Camera
-   getCapabilities() -> Array.<string>  // maybe ?
-```
-
-Questions:
-
-- Store tile layer extent in TileLayer or in TileGrid?  (not clear)
-
-Two concepts: tile coordinate system range and and available data extent.
-TileGrid extent is range (or validity extent) of the tile coordinate system.
-TileLayer extent is the available data extent. A particular TileGrid may range
-from 0,0 to 10,10. My cache may conform to that grid but I may only have tiles
-ranging from 2,2 to 8,8. When you need to wrap multiple worlds, you pay
-attention to the TileGrid extent. When you need to decide whether or not to
-bother requesting a tile, you pay attention to the TileLayer extent.
-
-- Who determines "best" resolution?  (static function?)
-
-
-Todo: if tile layer extent stored in TileLayer rather than TileGrid then extent
-will occasionally need to be passed to TileGrid functions for cropping.
-
-DESIGN ASSERTIONS
-=================
-
-Map
-
-- A map has a renderer (the map renderer).
-- A map has a camera.
-- Multiple maps can share the same camera.
-- A map has a layer list.
-
-Layer 
-
-- A layer can have multiple projections (the supported projections).
-- A layer advertizes the projections it supports.
-- A layer returns no data if asked data for an unsupported projection.
-
-LayerRendererOptions
-
-- A layer renderer options object stores view-related states for a layer.
-- Options include visibility, opacity, saturation, hue, etc.
-- A layer renderer options object has a layer.
-- Multiple layer renderer options can share the same layer.
-- In other words a layer can be viewed in different manners.
-
-Renderer
-
-- The map renderer responds to events.
-- The map renderer receives events from the camera.
-- The map renderer creates layer renderers.
-
-Control
-
-- A control may listen to map events.
-- A control may listen to camera events.
-- A map navigation control acts on the camera.
-
-MVC
-
-- Types can be described in MVC terms.
-- Models don't know what rendering means.
-- Maps are models.
-- Layers are models.
-- Layer views are models (sorry!).
-- Cameras are models.
-- Layer lists are collections.
-- Renderers are views.
-- Controls are views or controllers or both.
-- An attribution control is a view.
-- A map navigation control is a controller.
-- A zoom slider control is both a view and a controller.