Add explanations to api.md

README.md

@@ -5,16 +5,16 @@
 [gem-badge]: https://badge.fury.io/rb/feedstock.svg
 [gem-link]: https://rubygems.org/gems/feedstock
 
-Feedstock is a Ruby library for extracting information from an HTML/XML
-document and inserting it into an ERB template. Its primary purpose is to
-create a feed for a webpage that doesn't offer one.
+Feedstock is a Ruby library for extracting information from an HTML/XML document
+and inserting it into an ERB template. Its primary purpose is to create a feed
+for a webpage that doesn't offer one.
 
 ## Rationale
 
 I love RSS feeds.
 
-That's why I think it's a shame not every website has a feed. However, even
-when a website does have a feed, sometimes it doesn't include quite the mix
+That's why I think it's a shame not every website has a feed. However, even when
+a website does have a feed, sometimes it doesn't include quite the mix
 information that I want. I made Feedstock to solve those two problems.
 
 Feedstock is a Ruby library that you can use to create an Atom or RSS feed. It

api.md

@@ -1,15 +1,22 @@
 # API
 
+Feedstock provides its functionality through a single class-level method.
+
+## `Feedstock.feed`
+
 ```ruby
 Feedstock.feed(url, rules, format = :html, template = "#{__dir__}/../default.xml"
 ```
 
-## `url`
+The `feed` method takes up to four parameters and returns a String. Each
+parameter is explained in more detail below.
+
+### `url`
 
 The `url` parameter is a String and must resolve to either an HTML or XML
 document.
 
-## `rules`
+### `rules`
 
 The `rules` parameter is a Hash representing a collection of rules. `rules` has
 two mandatory keys and one optional key.
@@ -139,11 +146,11 @@ two mandatory keys and one optional key.
       can then use a Lambda to decide whether to keep or reject the entry. The
       Lambda must return a truthy value to keep the entry.
 
-## `format`
+### `format`
 
 The `format` parameter can be either `:html` or `:xml`. The default is `:html`.
 
-## `template`
+### `template`
 
 The `template` parameter should be a path to an ERB template into which the
 information and entries extracted from the document will be inserted. The ERB