From 0c7e4588c6c82a4930a71d36243d480d9b8bd457 Mon Sep 17 00:00:00 2001
From: Mickael Remond <mremond@process-one.net>
Date: Thu, 27 Jun 2019 10:21:33 +0200
Subject: [PATCH] Add initial documentation

---
 stanza/README.md | 80 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 80 insertions(+)
 create mode 100644 stanza/README.md

diff --git a/stanza/README.md b/stanza/README.md
new file mode 100644
index 0000000..fa93acf
--- /dev/null
+++ b/stanza/README.md
@@ -0,0 +1,80 @@
+# XMPP Stanza
+
+XMPP `stanza` package is use to parse, marshall and and unmarshal XMPP stanzas and nonzas.
+
+## Stanza creation
+
+When creating stanzas, you can use two approaches:
+
+1. You can create IQ, Presence or Message structs, set the fields and manually prepare extensions struct to add to the
+stanza.
+2. You can use `stanza` Builder providing 
+
+The methods are equivalent and you can use whatever suits you best. The Builder will generate the same type of
+struct that you can build by hand. 
+
+### Composing stanzas manually with structs
+
+Here is for example how you would generate an IQ discovery result:
+
+	iqResp := stanza.NewIQ(stanza.Attrs{Type: "result", From: iq.To, To: iq.From, Id: iq.Id, Lang: "en"})
+	identity := stanza.Identity{
+		Name:     opts.Name,
+		Category: opts.Category,
+		Type:     opts.Type,
+	}
+	payload := stanza.DiscoInfo{
+		XMLName: xml.Name{
+			Space: stanza.NSDiscoInfo,
+			Local: "query",
+		},
+		Identity: identity,
+		Features: []stanza.Feature{
+			{Var: stanza.NSDiscoInfo},
+			{Var: stanza.NSDiscoItems},
+			{Var: "jabber:iq:version"},
+			{Var: "urn:xmpp:delegation:1"},
+		},
+	}
+	iqResp.Payload = &payload
+
+### Using Builder
+
+Here is for example how you would generate an IQ discovery result using Builder:
+
+	b := stanza.NewBuilder()
+	iq := b.IQ(stanza.Attrs{Type: "get", To: "service.localhost", Id: "disco-get-1"})
+
+	payload := b.DiscoInfo()
+	identity := b.Identity("Test Component", "gateway", "service")
+	payload.SetFeatures(stanza.NSDiscoInfo, stanza.NSDiscoItems, "jabber:iq:version", "urn:xmpp:delegation:1").
+		SetIdentities(identity)
+
+	iq.Payload = payload
+
+## Payload and extensions
+
+### Message
+
+### Presence
+
+### IQ
+
+IQ (Information Queries) contain a payload associated with the request and possibly an error. The main difference with
+Message and Presence extension is that you can only have one payload per IQ. The XMPP specification does not support
+having multiple payloads.
+
+Here is the list of structs implementing IQPayloads:
+
+- BindBind
+- Pubsub
+
+Finally, when the payload of the parsed stanza is unknown, the parser will provide the unknown payload as a generic
+`Node` element. You can also use the Node struct to add custom information on stanza generation. However, in both cases,
+you may also consider [adding your own custom extensions on stanzas]().
+
+
+## Adding your own custom extensions on stanzas
+
+Extensions are registered on launch using the `Registry`. It can be used to register you own custom payload. You may
+want to do so to support extensions we did not yet implement, or to add your own custom extensions to your XMPP stanzas.