docs: Various improvements

* Explain the Text.codec property a little (closes #3171)
* Clarified TMX docs about image collection tilesets (closes #2117)
* Clarified saving of class properties in the TMX format (closes #3227)
* Documented scripting runtime in the manual (closes #3233)
* Made sure all classes have at least some description (closes #3239)
* Documented change signals (closes #3240, closes #3246)
* Noted that <terraintypes>, <terrain> and the `terrain` attribute
  are deprecated since Tiled 1.5 (closes #3169)

docs/reference/scripting.rst

@@ -27,6 +27,17 @@ JavaScript context.
     A few example scripts and links to existing Tiled extensions are provided
     at the Tiled Extensions repository: https://github.com/mapeditor/tiled-extensions
 
+
+JavaScript Host Environment
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Tiled uses the JavaScript engine shipping with Qt's `QML module`_. The QML
+runtime generally implements the 7th edition of the standard, with some
+additions. See the `JavaScript Host Environment`_ documentation for details.
+
+It may also be helpful to check out the `List of JavaScript Objects and
+Functions`_ that are available.
+
 .. note::
 
     The full scripting API and support for ECMAScript 7 features are only
@@ -106,4 +117,7 @@ __filename
     get called. If you need it there, copy the value to local scope.
 
 .. _Tiled Scripting API: https://www.mapeditor.org/docs/scripting/
+.. _JavaScript Host Environment: https://doc.qt.io/qt-5/qtqml-javascript-hostenvironment.html
+.. _List of JavaScript Objects and Functions: https://doc.qt.io/qt-5/qtqml-javascript-functionlist.html
+.. _QML module: https://doc.qt.io/qt-5/qtqml-index.html
 .. _@mapeditor/tiled-api: https://www.npmjs.com/package/@mapeditor/tiled-api

docs/reference/tmx-changelog.rst

@@ -11,8 +11,8 @@ Tiled 1.8
    type is saved as the new ``propertytype`` attribute on the
    :ref:`tmx-property` element.
 -  The :ref:`tmx-property` element can now contain a :ref:`tmx-properties`
-   element, in case the property value is a class. In this case the ``type``
-   attribute is set to the new value ``class``.
+   element, in case the property value is a class and at least one member value
+   has been set. The ``type`` attribute will have the new value ``class``.
 -  Added ``parallaxoriginx`` and ``parallaxoriginy`` attributes to the
    :ref:`tmx-map` element.
 -  Added ``repeatx`` and ``repeaty`` attributes to the :ref:`tmx-imagelayer`

docs/reference/tmx-map-format.rst

@@ -145,13 +145,19 @@ Can contain at most one: :ref:`tmx-chunksize`, :ref:`tmx-export`
    there. These two attributes are kept in the TMX map, since they are
    map specific.)
 -  **name:** The name of this tileset.
--  **tilewidth:** The (maximum) width of the tiles in this tileset.
+-  **tilewidth:** The (maximum) width of the tiles in this tileset. Irrelevant
+   for image collection tilesets, but stores the maximum tile width.
 -  **tileheight:** The (maximum) height of the tiles in this tileset.
+   Irrelevant for image collection tilesets, but stores the maximum tile
+   height.
 -  **spacing:** The spacing in pixels between the tiles in this tileset
-   (applies to the tileset image, defaults to 0)
+   (applies to the tileset image, defaults to 0). Irrelevant for image
+   collection tilesets.
 -  **margin:** The margin around the tiles in this tileset (applies to the
-   tileset image, defaults to 0)
--  **tilecount:** The number of tiles in this tileset (since 0.13)
+   tileset image, defaults to 0). Irrelevant for image collection tilesets.
+-  **tilecount:** The number of tiles in this tileset (since 0.13). Note that
+   there can be tiles with a higher ID than the tile count, in case the tileset
+   is an image collection from which tiles have been removed.
 -  **columns:** The number of tile columns in the tileset. For image
    collection tilesets it is editable and is used when displaying the
    tileset. (since 0.15)
@@ -162,15 +168,18 @@ Can contain at most one: :ref:`tmx-chunksize`, :ref:`tmx-export`
    reasons. When unspecified, tile objects use ``bottomleft`` in orthogonal mode
    and ``bottom`` in isometric mode. (since 1.4)
 
+A tileset can be either *based on a single image*, which is cut into tiles
+based on the given parameters, or a *collection of images*, in which case each
+tile defines its own image. In the first case there is a single child
+:ref:`tmx-image` element. In the latter case, each child
+:ref:`tmx-tileset-tile` element contains an :ref:`tmx-image` element.
+
 If there are multiple ``<tileset>`` elements, they are in ascending
 order of their ``firstgid`` attribute. The first tileset always has a
 ``firstgid`` value of 1. Since Tiled 0.15, image collection tilesets do
 not necessarily number their tiles consecutively since gaps can occur
 when removing tiles.
 
-Image collection tilesets have no ``<image>`` tag. Instead, each tile has
-an ``<image>`` tag.
-
 Can contain at most one: :ref:`tmx-image`, :ref:`tmx-tileoffset`,
 :ref:`tmx-grid` (since 1.0), :ref:`tmx-properties`, :ref:`tmx-terraintypes`,
 :ref:`tmx-wangsets` (since 1.1), :ref:`tmx-tileset-transformations` (since 1.5)
@@ -233,6 +242,10 @@ Can contain at most one: :ref:`tmx-data`
 <terraintypes>
 ~~~~~~~~~~~~~~
 
+**Deprecated:** This element has been deprecated since Tiled 1.5, in favour of
+the :ref:`tmx-wangsets` element, which is more flexible. Tilesets containing
+terrain types are automatically saved with a Wang set instead.
+
 This element defines an array of terrain types, which can be referenced
 from the ``terrain`` attribute of the ``tile`` element.
 
@@ -243,6 +256,9 @@ Can contain any number: :ref:`tmx-terrain`
 <terrain>
 ^^^^^^^^^
 
+**Deprecated:** This element has been deprecated since Tiled 1.5, in favour of
+the :ref:`tmx-wangcolor` element.
+
 -  **name:** The name of the terrain type.
 -  **tile:** The local tile-id of the tile that represents the terrain
    visually.
@@ -271,10 +287,11 @@ tiles (e.g. to extend a Wang set by transforming existing tiles).
 -  **id:** The local tile ID within its tileset.
 -  **type:** The type of the tile. Refers to an object type and is used
    by tile objects. (optional) (since 1.0)
--  **terrain:** Defines the terrain type of each corner of the tile,
+-  *terrain:* Defines the terrain type of each corner of the tile,
    given as comma-separated indexes in the terrain types array in the
    order top-left, top-right, bottom-left, bottom-right. Leaving out a
-   value means that corner has no terrain. (optional)
+   value means that corner has no terrain. (deprecated since 1.5 in favour of
+   :ref:`tmx-wangtile`)
 -  **probability:** A percentage indicating the probability that this
    tile is chosen when it competes with others while editing with the
    terrain tool. (defaults to 0)
@@ -318,8 +335,7 @@ Can contain any number: :ref:`tmx-wangset`
 <wangset>
 ^^^^^^^^^
 
-Defines a list of corner colors and a list of edge colors, and any
-number of Wang tiles using these colors.
+Defines a list of colors and any number of Wang tiles using these colors.
 
 -  **name:** The name of the Wang set.
 -  **tile:** The tile ID of the tile representing this Wang set.
@@ -708,6 +724,10 @@ integer (the ID of the referenced object, or 0 when no object is referenced).
 When used on objects in the Tile Collision Editor, they can only refer to
 other objects on the same tile.
 
+Class properties will have their member values stored in a nested
+:ref:`tmx-properties` element. Only the actually set members are saved. When no
+members have been set the ``properties`` element is left out entirely.
+
 When a string property contains newlines, the current version of Tiled
 will write out the value as characters contained inside the ``property``
 element rather than as the ``value`` attribute. It is possible that a