make docs more clear

docs/SUMMARY.md

@@ -3,7 +3,7 @@
 - [AddonScript](README.md)
 
 # Schema
-- [Addon Object](schema/root.md)
+- [Addon Object](schema/addon.md)
     - [AddonScript Object](schema/addonscript.md)
     - [File Object](schema/file.md)
         - [Install Object](schema/install.md)

docs/schema/addon.md

@@ -5,7 +5,7 @@
   "addonscript": {},
   "id": "myaddon",
   "namespace": "com.example",
-  "version": "1.0",
+  "version": "1.0.0",
   "files": [],
   "relations": [],
   "flags": ["server", "client"],
@@ -22,26 +22,28 @@ This is an [AddonScript object](addonscript.md) containing information about the
 
 ### id
 
-This is the ID of the addon. It should only contain **lowercase letters, numbers and dashes**.
+This is the ID of the addon.
+
+It should be written in the `kebab-case` format, meaning lowercase only and using `-` instead of spaces.
 
 ### version
 
-This is the version number of this version. It must follow [semver version naming conventions](https://semver.org/spec/v2.0.0.html), 
+This is the version number of this version. It must follow [semver versioning specifications](https://semver.org/spec/v2.0.0.html), 
 as they are used to compare versions.
 
 ## Optional properties
 
 ### namespace
 
-This is the namespace of the addon. 
+The namespace of the addon in a reverse-DNS format. Used to identify addons across repositories, if it is present.
 
 ### files
 
-This is an array of [file objects](file.md) including the files belonging to this version.
+This is an array of [file objects](file.md) including the files belonging to this addon.
 
 ### relations
 
-This is an array of [relation objects](relation.md) which represents related addons.
+This is an array of [relation objects](relation.md) which represent addons in relation to this one.
 
 ### flags
 
@@ -54,4 +56,4 @@ addons can be retrieved.
 
 ### meta
 
-This is a [meta object](meta.md).
+This is a [meta object](meta.md) containing metadata about the addon.

docs/schema/addonscript.md

@@ -6,5 +6,13 @@
 }
 ```
 
-Currently the AddonScript object only contains the version of AddonScript the file uses.
+Future fields may be added.
-In future versions, there may be other information added to this.
+
+# Required properties
+
+## version
+This is the version of the addonscript format the file is written in.
+
+The specification you are reading is for version 2. Version 1 is an old version which is deprecated,
+and doesn't have to be (and shouldn't be) implemented by tools using addonscript.
+

docs/schema/conditions.md

@@ -15,14 +15,138 @@ as optional relations in this version.
 
 ### require
 
-This is an array of addons, which are required for this relation or file.
+This is an array of addons, which are required for this relation or file and must be present.
 
 ### companion
 
-This is an array of addons, which have to be installed together with this
+This is an array of file IDs which go together with this relation/file.
-relation or file. In contrast to `require`, this is a two-way dependency, which means, that if this
+This field is fairly complex.
-file or relation is installed, the addons in the array also have to be installed and if one of the
+
-addons in the array are installed, this relation or file also have to be installed.
+The `companion` field is used to represent a relation between an optional file/relation, and an optional relation.
+This means, if one of them isn't optional, an error occurs.
+
+The behaviour can be summarized as such:
+
+1. The relation/file that declares companions is only installed if all companions are also installed.
+2. A relation that is a companion also will not be installed, unless **all** files/relations of that
+   relation declare it as a companion are also installed.
+
+This can be described as the relation and the relation/file that is a companion of the relation requiring **eachother**.
+The reason this isn't done by declaring a `require` condition both on the addon/file and the file, is that files
+cannot be referenced, as only addon-ids are used.
+
+<!--this table has to be in HTML and without indentation to allow markdown code blocks-->
+<table>
+<thead>
+<tr>
+<th>Name</th>
+<th>Type</th>
+<th>Installed if</th>
+<th>Flags</th>
+<th>Conditions</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>companion-relation</td>
+<td>relation</td>
+<td><em>example-file</em> is installed</td>
+<td>
+
+```json
+["optional"]
+```
+
+</td>
+<td>
+
+```json
+{}
+```
+
+</td>
+</tr>
+<tr>
+<td>example-file</td>
+<td>file</td>
+<td><em>companion-relation</em> is installed</td>
+<td>
+
+```json
+["optional"]
+```
+
+</td>
+<td>
+
+```json
+{
+  "companion": [
+    "companion-relation"
+  ]
+}
+```
+
+</td>
+</tr>
+</tbody>
+</table>
+
+An example of this would be to present alternative files for different modloaders in the case of a mod.
+Let's consider this example addon:
+
+```json
+{
+  "addonscript": { "version": 2 },
+  "id": "example-addon",
+  "version": "0.1.0",
+  "relations": [
+    {
+      "id": "forge",
+      "version": "37.0",
+      "flags": ["optional"]
+    },
+    {
+      "id": "fabric",
+      "version": "9.0",
+      "flags": ["optional"]
+    },
+    {
+      "id": "fabric-api",
+      "version": "0.42.1",
+      "flags": ["optional"],
+      "conditions": {
+        "companion": ["fabric"]
+      }
+    }
+  ],
+  "files": [
+    {
+      "id": "example-addon-forge",
+      "url": "./example_addon_forge.jar",
+      "conditions": {
+        "companion": ["forge"]
+      },
+      "flags": ["optional"]
+    },
+    {
+      "id": "example-addon-fabric",
+      "url": "./example_addon_fabric.jar",
+      "conditions": {
+        "companion": ["fabric"]
+      },
+      "flags": ["optional"]
+    }
+  ]
+}
+```
+
+This example addon provides files for forge and fabric, the files both having their
+respective modloaders as companions. This allows a mod to ship files for both modloaders
+without using different addons.
+
+Also note that the addon also adds the `fabric` relation to the `fabric-api` relation.
+Thus it will also be installed if the fabric version of the mod is used.
 
 ### exclude
 

docs/schema/file.md

@@ -15,8 +15,10 @@
 
 ### id
 
-This is the ID of the file. It should only contain **lowercase letters, numbers and dashes**.
+This is the ID of the file.
+It should be written in the `kebab-case` format, meaning lowercase only and using `-` instead of spaces.
 
+<!--TODO: error if there are multiple relations with the same id and allow multiple urls-->
 If multiple file objects in the same array have the same ID, they are treated as the same file,
 which means that the first one of them in the array will be used unless it can't be retrieved from the URL,
 in which case the next one will be used as a fallback.
@@ -34,13 +36,11 @@ The order in the array corresponds to the order in which the installation steps
 
 ### flags
 
-This is an array of [flags](../flags.md) for this file. If this property is not present in a file object, the file
+This is an array of [flags](../flags.md) for this file. If this property is not present in a file object, the file will use the default flags.
-will have the flags which are set as default for files, or if no default was set, it will inherit the flags from the
-associated version, which are applicable for files.
 
 ### sha1
 
-This is the sha1 checksum of the file. Although the checksum is optional, it is recommended to use it.
+This is the sha1 checksum of the file. Although the checksum is optional, it is recommended.
 
 ### conditions
 

docs/schema/meta.md

@@ -22,4 +22,51 @@
 
 ## Optional properties
 
+### addon
+An [addon mata](#addon-meta-object) object.
 
+### version
+A [version mata](#version-meta-object) object.
+
+### additional
+This object can contain any arbitrary data,
+
+# Addon Meta Object
+
+## Optional Properties
+
+### name
+The full, human-readable name of the addon. This is what a program such as a launcher should
+display to the user.
+
+### icon
+A path to the icon of the addon. This path should point to an image file of small resolution
+which is ideally square. It can be dispayed to users in programs.
+
+### description
+A path to a description file for the addon. The file should be in CommonMark markdown.
+
+### summary
+A short description of the addon, to be shown in lists and menus where the addon is shown aside others.
+
+### website
+A URL to a website about the addon
+
+### source
+A URL to the source code of the addon.
+
+### issues
+A URL to an issue tracker for the addon.
+
+### contributors
+An array of people who have contributed to the addon.
+
+# Version Meta Object
+
+## Optional properties
+
+### changelog
+A path to a changelog file for the addon.
+
+### timestamp
+A unix timestamp of the time and date of the version's release.

docs/schema/relation.md

@@ -3,7 +3,7 @@
 ```json
 {
   "id": "namespace:othermod",
-  "version": "[1.0,)",
+  "version": "1.0",
   "repositories": ["repo1"],
   "flags": [],
   "conditions": {}
@@ -18,21 +18,20 @@ This is the ID or namespaced ID of the addon this relation refers to.
 
 ### version
 
+<!--TODO: update link one PR is merged-->
 This is a [semver version range](https://github.com/semver/semver/pull/584) of supported versions of this relation.
 
 ## Optional properties
 
 ### repositories
 
-This is an array of [repository](repository.md) IDs. This are the repositories, from where AddonScript should try to get this relation from,
+This is an array of [repository](repository.md) IDs. These are the repositories, from which AddonScript should try to get this relation from,
-in the order as they are ordered in the array. If this property is not set or the array is empty, AddonScript will try to resolve the relation by
+in the order as they are specified in the array. If this property is not set or the array is empty, AddonScript will try to resolve the relation by
 the namespace from all defined repositories.
 
 ### flags
 
-This is an array of [flags](../flags.md) for this relation. If this property is not present in a relation object, the relation
+This is an array of [flags](../flags.md) for this relation. If this property is not present in a relation object, the relation will use the default flags.
-will have the flags which are set as default for relations or, if no default was set, it will inherit the flags
-which are applicable for relations from the associated version.
 
 ### conditions