diff --git a/doc/conf.json b/apidoc/conf.json similarity index 78% rename from doc/conf.json rename to apidoc/conf.json index 842c424266..72bc7c9173 100644 --- a/doc/conf.json +++ b/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" diff --git a/doc/index.md b/apidoc/index.md similarity index 100% rename from doc/index.md rename to apidoc/index.md diff --git a/doc/plugins/exports.js b/apidoc/plugins/exports.js similarity index 100% rename from doc/plugins/exports.js rename to apidoc/plugins/exports.js diff --git a/doc/plugins/inheritdoc.js b/apidoc/plugins/inheritdoc.js similarity index 100% rename from doc/plugins/inheritdoc.js rename to apidoc/plugins/inheritdoc.js diff --git a/doc/template/README.md b/apidoc/template/README.md similarity index 100% rename from doc/template/README.md rename to apidoc/template/README.md diff --git a/doc/template/publish.js b/apidoc/template/publish.js similarity index 100% rename from doc/template/publish.js rename to apidoc/template/publish.js diff --git a/doc/template/static/scripts/prettify/Apache-License-2.0.txt b/apidoc/template/static/scripts/prettify/Apache-License-2.0.txt similarity index 100% rename from doc/template/static/scripts/prettify/Apache-License-2.0.txt rename to apidoc/template/static/scripts/prettify/Apache-License-2.0.txt diff --git a/doc/template/static/scripts/prettify/lang-css.js b/apidoc/template/static/scripts/prettify/lang-css.js similarity index 100% rename from doc/template/static/scripts/prettify/lang-css.js rename to apidoc/template/static/scripts/prettify/lang-css.js diff --git a/doc/template/static/scripts/prettify/prettify.js b/apidoc/template/static/scripts/prettify/prettify.js similarity index 100% rename from doc/template/static/scripts/prettify/prettify.js rename to apidoc/template/static/scripts/prettify/prettify.js diff --git a/doc/template/static/styles/jsdoc-default.css b/apidoc/template/static/styles/jsdoc-default.css similarity index 100% rename from doc/template/static/styles/jsdoc-default.css rename to apidoc/template/static/styles/jsdoc-default.css diff --git a/doc/template/static/styles/prettify-jsdoc.css b/apidoc/template/static/styles/prettify-jsdoc.css similarity index 100% rename from doc/template/static/styles/prettify-jsdoc.css rename to apidoc/template/static/styles/prettify-jsdoc.css diff --git a/doc/template/static/styles/prettify-tomorrow.css b/apidoc/template/static/styles/prettify-tomorrow.css similarity index 100% rename from doc/template/static/styles/prettify-tomorrow.css rename to apidoc/template/static/styles/prettify-tomorrow.css diff --git a/doc/template/tmpl/container.tmpl b/apidoc/template/tmpl/container.tmpl similarity index 100% rename from doc/template/tmpl/container.tmpl rename to apidoc/template/tmpl/container.tmpl diff --git a/doc/template/tmpl/details.tmpl b/apidoc/template/tmpl/details.tmpl similarity index 100% rename from doc/template/tmpl/details.tmpl rename to apidoc/template/tmpl/details.tmpl diff --git a/doc/template/tmpl/example.tmpl b/apidoc/template/tmpl/example.tmpl similarity index 100% rename from doc/template/tmpl/example.tmpl rename to apidoc/template/tmpl/example.tmpl diff --git a/doc/template/tmpl/examples.tmpl b/apidoc/template/tmpl/examples.tmpl similarity index 100% rename from doc/template/tmpl/examples.tmpl rename to apidoc/template/tmpl/examples.tmpl diff --git a/doc/template/tmpl/exceptions.tmpl b/apidoc/template/tmpl/exceptions.tmpl similarity index 100% rename from doc/template/tmpl/exceptions.tmpl rename to apidoc/template/tmpl/exceptions.tmpl diff --git a/doc/template/tmpl/fires.tmpl b/apidoc/template/tmpl/fires.tmpl similarity index 100% rename from doc/template/tmpl/fires.tmpl rename to apidoc/template/tmpl/fires.tmpl diff --git a/doc/template/tmpl/layout.tmpl b/apidoc/template/tmpl/layout.tmpl similarity index 100% rename from doc/template/tmpl/layout.tmpl rename to apidoc/template/tmpl/layout.tmpl diff --git a/doc/template/tmpl/mainpage.tmpl b/apidoc/template/tmpl/mainpage.tmpl similarity index 100% rename from doc/template/tmpl/mainpage.tmpl rename to apidoc/template/tmpl/mainpage.tmpl diff --git a/doc/template/tmpl/members.tmpl b/apidoc/template/tmpl/members.tmpl similarity index 100% rename from doc/template/tmpl/members.tmpl rename to apidoc/template/tmpl/members.tmpl diff --git a/doc/template/tmpl/method.tmpl b/apidoc/template/tmpl/method.tmpl similarity index 100% rename from doc/template/tmpl/method.tmpl rename to apidoc/template/tmpl/method.tmpl diff --git a/doc/template/tmpl/params.tmpl b/apidoc/template/tmpl/params.tmpl similarity index 100% rename from doc/template/tmpl/params.tmpl rename to apidoc/template/tmpl/params.tmpl diff --git a/doc/template/tmpl/properties.tmpl b/apidoc/template/tmpl/properties.tmpl similarity index 100% rename from doc/template/tmpl/properties.tmpl rename to apidoc/template/tmpl/properties.tmpl diff --git a/doc/template/tmpl/returns.tmpl b/apidoc/template/tmpl/returns.tmpl similarity index 100% rename from doc/template/tmpl/returns.tmpl rename to apidoc/template/tmpl/returns.tmpl diff --git a/doc/template/tmpl/source.tmpl b/apidoc/template/tmpl/source.tmpl similarity index 100% rename from doc/template/tmpl/source.tmpl rename to apidoc/template/tmpl/source.tmpl diff --git a/doc/template/tmpl/tutorial.tmpl b/apidoc/template/tmpl/tutorial.tmpl similarity index 100% rename from doc/template/tmpl/tutorial.tmpl rename to apidoc/template/tmpl/tutorial.tmpl diff --git a/doc/template/tmpl/type.tmpl b/apidoc/template/tmpl/type.tmpl similarity index 100% rename from doc/template/tmpl/type.tmpl rename to apidoc/template/tmpl/type.tmpl diff --git a/build.py b/build.py index 8227931ee0..57f952b949 100755 --- a/build.py +++ b/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. diff --git a/doc/tutorials/ol3.json b/doc/tutorials/ol3.json deleted file mode 100644 index f0c33cdb2b..0000000000 --- a/doc/tutorials/ol3.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "OpenLayers 3 Architecture" -} diff --git a/doc/tutorials/ol3.md b/doc/tutorials/ol3.md deleted file mode 100644 index 3b78e33c8c..0000000000 --- a/doc/tutorials/ol3.md +++ /dev/null @@ -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.`, 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. - extent Extent - getResolutions() -> Array.|null - fires 'change' // when data changes - -LayerArray - getResolutions() -> Array.|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. - extent ol.Extent - xEast boolean - ySouth boolean - origin(s) Coord|Array. - 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. ? - getTileCoordPriority(tileCoord) -> number // private - enqueueTile(Tile) - -VectorLayer - forEachFeature(resolution, extent, projection, function(Feature)) - -Renderer - target HTMLDivElement - map Map - camera Camera - getCapabilities() -> Array. // 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.