Permalink
Browse files

Overhaul API documentation

  • Loading branch information...
1 parent cb58900 commit fb8e28c2f294aaf70bbb21da2d1e477610c2c07b @grncdr grncdr committed Apr 10, 2012
Showing with 192 additions and 85 deletions.
  1. +11 −10 README.rst
  2. +2 −1 doc/_static/sidebar.js
  3. +0 −1 doc/_templates/projectlinks.html
  4. +113 −2 doc/api.rst
  5. +1 −1 doc/handler_context.rst
  6. +65 −70 lazorse.coffee
View
@@ -1,19 +1,20 @@
Lazorse!
========
-Lazorse is a web-framework with a strong emphasis on extensibility and
-separation of various concerns into independant middleware layers.
-
-It includes middleware to route requests, coerce parameters, dispatch to handlers,
-and render a response.
-It borrows heavily from `other`_ `awesome`_ nodejs
-`web frameworks`_ but with a couple of twists designed to make writing
-machine-consumable ReSTful APIs a little easier. Because it's all "just
+Lazorse is a resource-oriented web-framework with a strong emphasis on
+extensibility and the separation of various concerns into independent
+middleware_ layers.
+
+It includes middleware to find a resource, coerce URL parameters, dispatch to
+HTTP method handlers, and render a response.
+
+It borrows heavily from other_ awesome_ node.js `web frameworks`_ but with a
+couple of twists designed to make writing machine-consumable ReSTful APIs a little easier. Because it's all "just
middleware", you can also pull out and re-arrange the various pieces to better
suit the needs of your application.
-.. _uri template rfc: http://tools.ietf.org/html/draft-gregorio-uritemplate-07
-.. _web frameworks: http://expressjs.com
+.. _middleware: http://stephensugden.com/middleware_guide/
+.. _web frameworks: http://expressjs.com/
.. _other: http://zappajs.org
.. _awesome: https://github.com/kadirpekel/coffeemate
View
@@ -10,7 +10,7 @@ $(document).ready(function() {
var sectionNames = {}
var sections = $('div.section').get().map(function (node) {
node.yTop = yOffset(node)
- var header = $(node).children('h1, h2').first()
+ var header = $(node).children('h1, h2, h3').first()
node.yBottom = yOffset(header.get(0)) + header.outerHeight()
sectionNames[node.id] = node
return node
@@ -31,6 +31,7 @@ $(document).ready(function() {
}
function highlightSection(section) {
+ if (!section) return
$(".currentsection").removeClass('currentsection')
$(section).addClass('currentsection')
$(".sphinxsidebar a[href='#" + section.id + "']")
@@ -1,7 +1,6 @@
<h3>Project Links</h3>
<ul>
{% block projectlinks %}
-<li><a href="{{ pathto(master_doc) }}">Documentation Index</a></li>
<li><a href="http://github.com/BetSmartMedia/Lazorse">Source on Github</a></li>
<li><a href="http://github.com/BetSmartMedia/Lazorse/tree/master/examples">Example Apps</a></li>
{% endblock %}
View
@@ -2,5 +2,116 @@
API documentation
=================
-.. automodule:: lazorse
- :members:
+Exported API
+============
+
+The main export is a function that takes a "builder" function and constructs a
+`LazyApp <#app-building>`_ instance with it::
+
+ lazorseApp = require('lazorse') ->
+ # Build your app here
+
+Or, if you'd rather get back a connect app ready for more ``.use()`` calls::
+
+ connectApp = require('lazorse').connect ->
+ # Again, build the app here
+
+Finally, if you'd rather start a server automatically after the app is built::
+
+ require('lazorse').server port: 1234, host: '0.0.0.0', ->
+ # A pattern is emerging...
+
+The rest of the API is made up of the methods on ``LazyApp`` which are available
+on ``@`` (``this``) to your builder function.
+
+App-building
+====================
+
+The builder function is called with it's ``@`` context set to the partially
+constructed ``LazyApp`` instance, it builds out the app by calling methods
+and/or modifying properties on ``@``
+
+App-building properties
+-----------------------
+
+The following properties on ``@`` can be set to alter default behaviours:
+
+``@indexPath``, ``@examplePath`` and ``@parameterPath``:
+ Prefixes for the location of the `default resources`_. You can disable
+ any of these resources by setting their path prefix to ``false``.
+
+ Defaults: ``'/'``, ``'/examples'``, ``'/parameters'``
+
+``@passErrors``
+ Setting this to ``true`` will cause unrecognized errors to be passed to
+ ``@next()`` by :meth:`lazorse::LazyApp.handleErrors`.
+
+ Default: false
+
+App-building methods
+-----------------------
+
+.. automethod:: lazorse::LazyApp.resource
+
+.. automethod:: lazorse::LazyApp.helper
+
+ Lazorse installs 4 default helpers into every app:
+
+ * ``@data`` - Use this as a callback to asynchronous functions that use the
+ ``callback(err, result)`` idiom.
+ * ``@ok`` - Sets ``@res.data`` and call @next unconditionally.
+ * ``@error`` - Given a constructor function or a name registered with
+ :meth:`error`, and additional constructor arguments, constructs an error
+ and passes it to ``@next``.
+ * ``@link`` - Return a URL path to a resource given it's shortName and
+ a template expansion context object.
+
+ These are added before the builder function is called, so it's possible
+ (though not recommended) to over-ride or remove them by modifying
+ ``@helpers``.
+
+.. automethod:: lazorse::LazyApp.coerce
+.. automethod:: lazorse::LazyApp.render
+.. automethod:: lazorse::LazyApp.error
+.. automethod:: lazorse::LazyApp.include
+.. automethod:: lazorse::LazyApp.before
+
+Middleware Methods
+==================
+
+These methods act as Connect middleware. They remain bound to the app so you
+can safely pass them to connects ``.use()`` method without wrapping them in a
+callback function.
+
+.. automethod:: lazorse::LazyApp.findResource
+.. automethod:: lazorse::LazyApp.coerceParams
+.. automethod:: lazorse::LazyApp.dispatchHandler
+.. automethod:: lazorse::LazyApp.renderResponse
+.. automethod:: lazorse::LazyApp.handleErrors
+
+Default Resources
+=================
+
+Lazorse adds three default resources to every app (unless they are disabled_):
+
+Index (default path ``/``):
+ Returns metadata for all of the *named* resources in the app, including URI
+ templates, descriptions, and supported HTTP methods, and links to example
+ requests if any are defined.
+
+Examples (default path ``/examples/{shortName}``):
+ Responds with an array of all of the example requests for the named resource.
+
+Parameters (default paths ``/parameters/`` and ``/parameters/{parameterName}``)
+ Responds with the documentation string for all, or the specifically named,
+ URL parameter coercions given to :meth:`lazorse::LazyApp.coerce`.
+
+.. _disabled: #app-building-properties
+
+Request Contexts
+================
+
+Every request has a special `request context` assigned to it. This context is
+shared by all of the coercions, helpers, and handlers used in a single request.
+
+.. include:: handler_context.rst
View
@@ -3,7 +3,7 @@ The context is made up of 2 objects in a delegation chain:
1. An object containing URI Template variables, which delegates to:
2. A request context object containing:
- * All helpers defined for the app (using :meth:`lazorse::LazyApp.helper`)
+ * All helpers defined for the app using :meth:`~lazorse::LazyApp.helper`.
* ``app``: The lazorse app
* ``req``: The request object from node (via connect)
* ``res``: The response object from node (via connect)
Oops, something went wrong.

0 comments on commit fb8e28c

Please sign in to comment.