update spec with descriptions

docs/src/_spec.json

@@ -1,6 +1,7 @@
 [
 	{
 		"title": "Organisations",
+		"description": "Organisations represent a top-level grouping entity. There may be many organisations defined in a single deployment.",
 		"package": "crust",
 		"entrypoint": "organisation",
 		"apis": {
@@ -32,6 +33,7 @@
 	},
 	{
 		"title": "Teams",
+		"description": "An organisation may have many teams. Teams may have many channels available. Access to channels may be shared between teams.",
 		"package": "crust",
 		"entrypoint": "team",
 		"apis": {
@@ -67,6 +69,7 @@
 	},
 	{
 		"title": "Channels",
+		"description": "A channel is a representation of a sequence of messages. It has meta data like channel subject. Channels may be public, private or direct (between two users).",
 		"package": "crust",
 		"entrypoint": "channel",
 		"apis": {
@@ -164,6 +167,7 @@
 	},
 	{
 		"title": "Files",
+		"description": "The Files API is an abstraction over messages that have been sent with a file attachment.",
 		"package": "crust",
 		"entrypoint": "file",
 		"apis": {

docs/src/channel.json

@@ -1,5 +1,6 @@
 {
   "Title": "Channels",
+  "Description": "A channel is a representation of a sequence of messages. It has meta data like channel subject. Channels may be public, private or direct (between two users).",
   "Package": "crust",
   "Interface": "Channel",
   "Path": "/channel",

docs/src/file.json

@@ -1,5 +1,6 @@
 {
   "Title": "Files",
+  "Description": "The Files API is an abstraction over messages that have been sent with a file attachment.",
   "Package": "crust",
   "Interface": "File",
   "Path": "/file",

docs/src/message.md

@@ -0,0 +1,19 @@
+Messages represent individual messages in the chat system. Messages are typed, indicating the event which triggered the message.
+
+Currently expected message types are:
+
+| Name | Description |
+| ---- | ----------- |
+| CREATE | The first message when the channel is created |
+| TOPIC | A member changed the topic of the channel |
+| RENAME | A member renamed the channel |
+| MESSAGE | A member posted a message to the channel |
+| FILE | A member uploaded a file to the channel |
+
+The following event types may be sent with a message event:
+
+| Name | Description |
+| ---- | ----------- |
+| CREATED | A message has been created on a channel |
+| EDITED | A message has been edited by the sender |
+| REMOVED | A message has been removed by the sender |

docs/src/organisation.json

@@ -1,5 +1,6 @@
 {
   "Title": "Organisations",
+  "Description": "Organisations represent a top-level grouping entity. There may be many organisations defined in a single deployment.",
   "Package": "crust",
   "Interface": "Organisation",
   "Path": "/organisation",

docs/src/team.json

@@ -1,5 +1,6 @@
 {
   "Title": "Teams",
+  "Description": "An organisation may have many teams. Teams may have many channels available. Access to channels may be shared between teams.",
   "Package": "crust",
   "Interface": "Team",
   "Path": "/team",