From 4def0c6a841c4231003ac8db544df4a67c5e3ddc Mon Sep 17 00:00:00 2001 From: Tim Schaub Date: Mon, 23 Sep 2013 23:50:57 +0200 Subject: [PATCH] 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). --- {doc => apidoc}/conf.json | 7 +- {doc => apidoc}/index.md | 0 {doc => apidoc}/plugins/exports.js | 0 {doc => apidoc}/plugins/inheritdoc.js | 0 {doc => apidoc}/template/README.md | 0 {doc => apidoc}/template/publish.js | 0 .../scripts/prettify/Apache-License-2.0.txt | 0 .../static/scripts/prettify/lang-css.js | 0 .../static/scripts/prettify/prettify.js | 0 .../template/static/styles/jsdoc-default.css | 0 .../template/static/styles/prettify-jsdoc.css | 0 .../static/styles/prettify-tomorrow.css | 0 {doc => apidoc}/template/tmpl/container.tmpl | 0 {doc => apidoc}/template/tmpl/details.tmpl | 0 {doc => apidoc}/template/tmpl/example.tmpl | 0 {doc => apidoc}/template/tmpl/examples.tmpl | 0 {doc => apidoc}/template/tmpl/exceptions.tmpl | 0 {doc => apidoc}/template/tmpl/fires.tmpl | 0 {doc => apidoc}/template/tmpl/layout.tmpl | 0 {doc => apidoc}/template/tmpl/mainpage.tmpl | 0 {doc => apidoc}/template/tmpl/members.tmpl | 0 {doc => apidoc}/template/tmpl/method.tmpl | 0 {doc => apidoc}/template/tmpl/params.tmpl | 0 {doc => apidoc}/template/tmpl/properties.tmpl | 0 {doc => apidoc}/template/tmpl/returns.tmpl | 0 {doc => apidoc}/template/tmpl/source.tmpl | 0 {doc => apidoc}/template/tmpl/tutorial.tmpl | 0 {doc => apidoc}/template/tmpl/type.tmpl | 0 build.py | 12 +- doc/tutorials/ol3.json | 3 - doc/tutorials/ol3.md | 274 ------------------ 31 files changed, 9 insertions(+), 287 deletions(-) rename {doc => apidoc}/conf.json (78%) rename {doc => apidoc}/index.md (100%) rename {doc => apidoc}/plugins/exports.js (100%) rename {doc => apidoc}/plugins/inheritdoc.js (100%) rename {doc => apidoc}/template/README.md (100%) rename {doc => apidoc}/template/publish.js (100%) rename {doc => apidoc}/template/static/scripts/prettify/Apache-License-2.0.txt (100%) rename {doc => apidoc}/template/static/scripts/prettify/lang-css.js (100%) rename {doc => apidoc}/template/static/scripts/prettify/prettify.js (100%) rename {doc => apidoc}/template/static/styles/jsdoc-default.css (100%) rename {doc => apidoc}/template/static/styles/prettify-jsdoc.css (100%) rename {doc => apidoc}/template/static/styles/prettify-tomorrow.css (100%) rename {doc => apidoc}/template/tmpl/container.tmpl (100%) rename {doc => apidoc}/template/tmpl/details.tmpl (100%) rename {doc => apidoc}/template/tmpl/example.tmpl (100%) rename {doc => apidoc}/template/tmpl/examples.tmpl (100%) rename {doc => apidoc}/template/tmpl/exceptions.tmpl (100%) rename {doc => apidoc}/template/tmpl/fires.tmpl (100%) rename {doc => apidoc}/template/tmpl/layout.tmpl (100%) rename {doc => apidoc}/template/tmpl/mainpage.tmpl (100%) rename {doc => apidoc}/template/tmpl/members.tmpl (100%) rename {doc => apidoc}/template/tmpl/method.tmpl (100%) rename {doc => apidoc}/template/tmpl/params.tmpl (100%) rename {doc => apidoc}/template/tmpl/properties.tmpl (100%) rename {doc => apidoc}/template/tmpl/returns.tmpl (100%) rename {doc => apidoc}/template/tmpl/source.tmpl (100%) rename {doc => apidoc}/template/tmpl/tutorial.tmpl (100%) rename {doc => apidoc}/template/tmpl/type.tmpl (100%) delete mode 100644 doc/tutorials/ol3.json delete mode 100644 doc/tutorials/ol3.md 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.