Merge taataa/feature-docs

Improve docs

README.md

@@ -41,6 +41,27 @@ See [taataa.github.io/tapspace](http://taataa.github.io/tapspace) for:
 - [API Reference](https://taataa.github.io/tapspace/api/v2/)
 - [Developer's Cheat Sheet](http://taataa.github.io/tapspace/dev)
 
+**In a nutshell**, Tapspace.js consists of component classes that each wrap an HTML element.
+These classes allow the elements to be positioned freely on a transformable and infinite space.
+A hierarchy of these components form a subtree in the browser DOM.
+This subtree, which we call the *affine subtree*, has a tensor matrix backbone that
+makes projecting points, vectors, and other geometry between the components
+**extremely easy**.
+
+Most of the methods in Tapspace, like Viewport:translateBy,
+take in tensor geometry objects, like Point, Distance, and Box.
+The tensor aspect makes the geometries exist in all coordinate spaces at the same time,
+practically freeing you from the need to think how to transit geometry from
+an HTML element coordinate space into another coordinate space like onto the viewport or another element.
+This comes handy with – and does enable – wild arrangements of components in various scales and angles,
+and dynamic interaction driven with multitouch, mouse, or other input devices.
+
+Under the hood Tapspace.js uses CSS 2D transforms. In comparison with CSS 3D transforms,
+2D offers unbeatable rendering speed, full browser compatibility, and ease of navigation.
+Even CSS 2D transforms can slow down under thousands of elements and break in deep depths.
+Large, deep, or infinite visualisations can use tapspace.loaders.TreeLoader
+to **escape the limits of browser rendering engine and floating point arithmetics.**
+
 ## Supporters
 
 We have developed Tapspace.js in collaboration with the following organizations.

docs/api/index.md

@@ -3,6 +3,6 @@
 Choose version:
 
 - [Tapspace v1.6.0 API Docs](https://taataa.github.io/tapspace/api/v1/)
-- [Tapspace v2.0.0-alpha API Docs](v2/)
+- [Tapspace v2.0.0 API Docs](v2/)
 
 Or go [back to introduction](../)

docs/api/v2/index.md

@@ -2,15 +2,20 @@
 # Tapspace API Documentation v2.0.0-alpha.22
 
 
-Welcome to Tapspace.js API documentation.
-Build your zoomable application with the tools documented here.
-For older versions, see [Tapspace.js API docs index](https://taataa.github.io/tapspace/api/)
+Choose version: [v1](https://taataa.github.io/tapspace/api/) – [v2](#)
 
-This document follows these naming conventions: `ClassName`, `namespace`, `.CONSTANT`, `.classMethod()`, `:instanceProperty`, `:instanceMethod()`, `[optionalParameter]`, and `optionalProperty?`.
+**Welcome** to Tapspace.js API documentation.
+Build your zoomable application with the classes and methods documented here.
+This document is generated with [yamdog](https://github.com/axelpale/yamdog).
 
-See also: [Introduction](https://taataa.github.io/tapspace/) – [Examples](https://taataa.github.io/tapspace/#examples) – [Tutorial](https://taataa.github.io/tapspace/tutorial/) - [Glossary](https://taataa.github.io/tapspace/glossary/v2/) - [GitHub](https://github.com/taataa/tapspace)
+You might want to look [examples](https://taataa.github.io/tapspace/#examples)
+and [tutorial](https://taataa.github.io/tapspace/tutorial/) to learn how to combine
+classes and method calls to build your first zoomable applications. Rely on the API documentation
+when you are ready to get wild.
 
-This document is generated with [yamdog](https://github.com/axelpale/yamdog).
+**Naming convention** of the document: `ClassName`, `namespace`, `.CONSTANT`, `.classMethod()`, `:instanceProperty`, `:instanceMethod()`, `[optionalParameter]`, and `optionalProperty?`.
+
+See also: [Introduction](https://taataa.github.io/tapspace/) – [Examples](https://taataa.github.io/tapspace/#examples) – [Tutorial](https://taataa.github.io/tapspace/tutorial/) - [Glossary](https://taataa.github.io/tapspace/glossary/v2/) - [GitHub](https://github.com/taataa/tapspace)
 
 
 
@@ -4714,6 +4719,7 @@ Source: [measureAll.js](https://github.com/taataa/tapspace/blob/master/lib/compo
 ## [tapspace](#tapspace).[components](#tapspacecomponents).[Viewport](#tapspacecomponentsviewport):[measureDilation](#tapspacecomponentsviewportmeasuredilation)(component)
 
 Measure dilation of the given component with respect to the viewport.
+In other words, get component's scale relative to the viewport.
 
 <p style="margin-bottom: 0"><strong>Parameters:</strong></p>
 

docs/api/v2/intro.js

@@ -1,11 +1,16 @@
 module.exports = `
-Welcome to Tapspace.js API documentation.
-Build your zoomable application with the tools documented here.
-For older versions, see [Tapspace.js API docs index](https://taataa.github.io/tapspace/api/)
+Choose version: [v1](https://taataa.github.io/tapspace/api/) – [v2](#)
 
-This document follows these naming conventions: \`ClassName\`, \`namespace\`, \`.CONSTANT\`, \`.classMethod()\`, \`:instanceProperty\`, \`:instanceMethod()\`, \`[optionalParameter]\`, and \`optionalProperty?\`.
+**Welcome** to Tapspace.js API documentation.
+Build your zoomable application with the classes and methods documented here.
+This document is generated with [yamdog](https://github.com/axelpale/yamdog).
 
-See also: [Introduction](https://taataa.github.io/tapspace/) – [Examples](https://taataa.github.io/tapspace/#examples) – [Tutorial](https://taataa.github.io/tapspace/tutorial/) - [Glossary](https://taataa.github.io/tapspace/glossary/v2/) - [GitHub](https://github.com/taataa/tapspace)
+You might want to look [examples](https://taataa.github.io/tapspace/#examples)
+and [tutorial](https://taataa.github.io/tapspace/tutorial/) to learn how to combine
+classes and method calls to build your first zoomable applications. Rely on the API documentation
+when you are ready to get wild.
 
-This document is generated with [yamdog](https://github.com/axelpale/yamdog).
+**Naming convention** of the document: \`ClassName\`, \`namespace\`, \`.CONSTANT\`, \`.classMethod()\`, \`:instanceProperty\`, \`:instanceMethod()\`, \`[optionalParameter]\`, and \`optionalProperty?\`.
+
+See also: [Introduction](https://taataa.github.io/tapspace/) – [Examples](https://taataa.github.io/tapspace/#examples) – [Tutorial](https://taataa.github.io/tapspace/tutorial/) - [Glossary](https://taataa.github.io/tapspace/glossary/v2/) - [GitHub](https://github.com/taataa/tapspace)
 `

lib/components/Viewport/measureDilation.js

@@ -5,6 +5,7 @@ module.exports = function (component) {
   // @Viewport:measureDilation(component)
   //
   // Measure dilation of the given component with respect to the viewport.
+  // In other words, get component's scale relative to the viewport.
   //
   // Parameters:
   //   component