diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..143471c
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,21 @@
+## 1.0.0 (August 23, 2016)
+
+First stable and documented release - however, the functionality or API has not changed from `0.0.3`.
+
+* __Documentation:__ Updated donation text.
+* __Documentation:__ Added documentation and a changelog.
+
+## 0.0.3 (May 10, 2016)
+
+* __Minor:__ Made the Riot query segment optional.
+* __Minor:__ Added mixin interface.
+* __Minor:__ Added support for `query.one`.
+* __Package:__ Changed `gulpfile` to use presets.
+
+## 0.0.2 (April 16, 2016)
+
+* _Patch:__ Added `.npmignore` file to ensure that `lib/` is included in the published module.
+
+## 0.0.1 (April 16, 2016)
+
+Initial release.
\ No newline at end of file
diff --git a/README.md b/README.md
index 4e82cf4..f9b63c7 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,11 @@
-# packagename
+# riot-query
-TODO
+A module for easily traversing through a Riot.js tag hierarchy, using a simple custom query language. Can be used stand-alone or as a tag mixin.
+
+## Why you might need this
+
+* Riot.js is inconsistent in how it exposes its `tags` - it will be an array if there are multiple, and a single element if there's only one. This means you constantly have to normalize the results.
+* While selecting direct descendants is easy, it's a lot trickier when you need to search in the entire hierarchy, for example because you have a wrapper element that `yield`s its content.
## License
@@ -8,9 +13,9 @@ TODO
## Donate
-My income consists largely of donations for my projects. If this module is useful to you, consider [making a donation](http://cryto.net/~joepie91/donate.html)!
+Maintaining open-source projects takes a lot of time, and the more donations I receive, the more time I can dedicate to open-source. If this module is useful to you, consider [making a donation](http://cryto.net/~joepie91/donate.html)!
-You can donate using Bitcoin, PayPal, Flattr, cash-in-mail, SEPA transfers, and pretty much anything else.
+You can donate using Bitcoin, PayPal, Flattr, cash-in-mail, SEPA transfers, and pretty much anything else. Thank you!
## Contributing
@@ -20,10 +25,163 @@ Build tool of choice is `gulp`; simply run `gulp` while developing, and it will
Be aware that by making a pull request, you agree to release your modifications under the licenses stated above.
+## Query language
+
+A query consists of two parts: a Riot query and a DOM query. Both are optional, but you must always specify *at least one of them*.
+
+In the Riot part of a query, the structure always refers to the hierarchy of *Riot tags*, not other DOM elements. In other words, the hierarchy follows the one you'd find in `this.tags`. In the DOM part of the query, you can specify DOM elements to select in the set of Riot tags that you've selected.
+
+The `riot-query` language is somewhat syntactically similar to shell expansion. Below is a reference chart:
+
+| Syntax | Meaning |
+|-----------------------------|---------------------------------------------------|
+| `foo` | Each `foo` tag. |
+| `foo/bar` | Each `bar` tag that is a direct descendant of a `foo` tag. |
+| `foo/**/bar` | Each `bar` tag that is a child of a `foo` tag, *anywhere* in its subtree - it does *not* have to be a direct descendant. |
+| `{foo,bar}` | Each `foo` and `bar` tag |
+| `foo/{bar,baz}` | Each `bar` and `baz` tag that is a direct descendant of a `foo` tag. |
+| `foo/{bar,baz,}` | Each `foo`, `foo/bar` and `foo/baz` tag (note the last comma!) |
+| `foo//.someClass` | Each DOM element matching `.someClass` that exists somewhere within a `foo` tag. |
+| `foo//.someClass > .sub` | Each DOM element matching `.someClass > .sub` that exists somewhere within a `foo` tag. |
+
+These are only some simplified examples - *any* combination of the above is valid, as long as the (optional) DOM part of the query comes last. `riot-query` uses a real query parser, so there are no edge cases.
+
## Usage
-TODO
+An example of a simple query:
+
+```
+menu-bar/{menu-button,menu-submenu}
+```
+
+This would select every `menu-button` and `menu-submenu` that is directly nested within a `menu-bar`.
+
+
+An example of a contrived, complex query:
+
+```
+foo/bar/**/{baz,qux/quz,something/{hai,bai},}/{duck,swan}//.domFoo .domBar
+```
+
+This would select every DOM element matching `.domFoo .domBar` that exists within any of the following paths:
+
+* `foo/bar/**/baz/duck`
+* `foo/bar/**/baz/swan`
+* `foo/bar/**/qux/quz/duck`
+* `foo/bar/**/qux/quz/swan`
+* `foo/bar/**/something/hai/duck`
+* `foo/bar/**/something/hai/swan`
+* `foo/bar/**/something/bai/duck`
+* `foo/bar/**/something/bai/swan`
+* `foo/bar/**/duck`
+* `foo/bar/**/swan`
+
+The last two might seem a little odd, but note the extra comma at the end of the first group - a trailing comma is considered to indicate an empty item, similar to how it works in Bash, and in `riot-query` that means that the entire segment is ignored.
+
+An example of making a query using `riot-query` as a mixin:
+
+```html
+
+
+ Text 1
+ Text 2
+
+
+
+
+```
+
+A similar example, but selecting DOM nodes rather than Riot tags:
+
+```html
+
+
+
+
+ Text 1
+
+
+
+ Text 2
+
+
+
+
+
+```
+
+An example using `riot-query` stand-alone rather than as a mixin:
+
+```html
+
+
+
+
+ Text 1
+
+
+
+ Text 2
+
+
+
+
+
+```
## API
-TODO
\ No newline at end of file
+### riotQuery(tag, query)
+
+Run a `query` on a given `tag`, and return the results.
+
+* __tag:__ The Riot.js tag to query from. This *cannot* be a regular DOM element, it *must* be a tag.
+* __query:__ The query to run, following the query syntax described above.
+
+If the `query` contains a DOM query, this function will return DOM elements. If it doesn't, it will return Riot tags. If only a DOM query is specified without a Riot query (eg. `//.someClass`), then `riot-query` will search through the DOM tree for the tag that `riotQuery` was called on.
+
+Keep in mind that if your query selects DOM nodes rather than Riot tags, __they will be returned as an array, not as a NodeList.__ Additionally, DOM queries will *also* include DOM elements in child tags, not just those that are a part of the tag you're querying from.
+
+### riotQuery.one(tag, query)
+
+The same as `riotQuery`, but it only ever returns the *first* result, without being wrapped in an array.
+
+### riotQuery.mixin
+
+A mixin object that you can pass into the `this.mixin` method for any Riot tag.
+
+## Mixin API
+
+### this.query(query)
+
+The same as `riotQuery`, but without the need to specify a `tag` - it will always apply to the current tag.
+
+### this.queryOne(query)
+
+The same as `riotQuery.one`, but without the need to specify a `tag`.
\ No newline at end of file
diff --git a/src/index.js b/src/index.js
index 75b6b0f..7f155d4 100644
--- a/src/index.js
+++ b/src/index.js
@@ -97,8 +97,6 @@ function query(tag, queryString) {
queryCache[queryString] = createQuery(queryString);
}
- // TODO: DOM traversal
-
return queryCache[queryString](tag);
}