Browse files

Updates boo's documentation to the new Sphinx format.

  • Loading branch information...
1 parent 37e65c1 commit 455f905b9aabbe4a2e78bb314584be3c7fec5b69 @robotlolita committed May 17, 2012
View
2 docs/Makefile
@@ -37,6 +37,8 @@ clean:
-rm -rf $(BUILDDIR)/*
html:
+ stylus -o ~/work/caffeine-theme/caffeine/static ~/work/caffeine-theme/caffeine/stylus/screen.styl
+ mv ~/work/caffeine-theme/caffeine/static/screen.css ~/work/caffeine-theme/caffeine/static/screen.css_t
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
View
64 docs/source/api/base.rst
@@ -0,0 +1,64 @@
+{} Base
+*******
+
+.. class:: Base
+ :module: boo
+
+ .. code-block:: haskell
+
+ Base :: { init! :: @this:Object*, Any... -> this }
+
+ The root object for basing all the OOP code. Provides all of *Boo's*
+ primitive combinators in an easy and extensible OOP-way.
+
+
+
+Creating instances
+==================
+
+.. function:: Base.make()
+ :noindex:
+
+ .. code-block:: haskell
+
+ make :: @this:Object, Any... -> Object <| this
+
+ Constructs new instances of the object the function is being applied to.
+
+ .. rst-class:: detail-link
+
+ :doc:`+ <base/make>`
+
+
+.. function:: Base.derive(sources...)
+ :noindex:
+
+ .. code-block:: haskell
+
+ derive :: @this:Object, (Object | DataObject)... -> Object <| this
+
+ Constructs a new object that inherits from the object this function is
+ being applied to, and extends it with the provided *mixins*.
+
+ .. rst-class:: detail-link
+
+ :doc:`+ <base/derive>`
+
+
+
+Summary
+=======
+
+.. code-block:: haskell
+
+ init! :: @this:Object*, Any... -> this
+ make :: @this:Object, Any... -> Object <| this
+ derive :: @this:Object, Any... -> Object <| this
+
+
+.. -------------------------------------------------------------------------
+.. toctree::
+ :hidden:
+
+ base/make
+ base/derive
View
36 docs/source/api/base/derive.rst
@@ -0,0 +1,36 @@
+λ derive()
+**********
+
+.. function:: Base.derive(sources...)
+ :module: boo
+
+ .. code-block:: haskell
+
+ derive :: @this:Object, (Object | DataObject)... -> Object <| this
+
+ Constructs a new object that inherits from the object this function is
+ being applied to, and extends it with the provided *mixins*.
+
+
+Derive provides a thin abstraction layer upon the primitive :func:`derive`,
+with the only difference being that instead of taking a *[[Prototype]]* as the first
+parameter, it uses the object the ``derive`` function has been applied to for
+that.
+
+.. code-block:: javascript
+
+ var Point2d = { x: 0, y: 0 }
+ var Point3d = boo.derive(Point2d, { z: 1 })
+
+
+ // Does mostly the same thing as:
+ var Point2d = Base.derive({ x: 0, y: 0 })
+ var Point3d = Point2d.derive({ z: 1 })
+
+
+Related functionality
+=====================
+
+:doc:`λ derive <../derive>`
+ The ``derive`` primitive function documentation page describes the
+ function's semantics in more details.
View
62 docs/source/api/base/make.rst
@@ -0,0 +1,62 @@
+λ make()
+********
+
+.. function:: Base.make()
+ :module: boo
+
+ .. code-block:: haskell
+
+ make :: @this:Object, Any... -> Object <| this
+
+ Constructs new instances of the object the function is being applied to.
+
+
+This is a generic method that will clone the current object and initialise it
+with an initialisation method (``init``). Such initialisation method is taken
+from the object the ``make`` method is applied to. This approach makes this
+method rather flexible:
+
+.. code-block:: javascript
+
+ var fruit = { init: function(name){ this.name = name
+ this.bites = 0 }
+ , eat: function(){ return this.bites++? 'Already eaten.'
+ : /* otherwise */ this.name + ' is being eaten.' }}
+
+ // This creates a new object with `fruit' as its prototype, and
+ // invokes `fruit's `init' method on it.
+ var apple = Base.make.call(fruit, 'Apple')
+
+ apple.eat()
+ // => 'Apple has been eaten.'
+ apple.eat()
+ // => 'Already eaten.'
+
+ // This creates a new object with `apple' as its prototype, and
+ // invokes `apple's `init' method on it. Since apple itself doesn't
+ // define an `init' method, it's taken from `fruit'.
+ var pie = Base.make.call(apple, 'Apple pie')
+ pie.eat()
+ // => 'Apple pie has been eaten.'
+
+
+The generic object on which ``make`` will be called should either not implement
+an ``init`` method at all, or match the following interface:
+
+.. code-block:: haskell
+
+ type Initialisable :: { init! :: @this:Object*, Any... -> this }
+
+
+
+Limitations
+===========
+
+While *JavaScript's* own ``new`` operator allows one to write factory functions
+that work seamlessly with ``new-ful`` invocations, the ``make`` method won't
+change the instance depending on what ``init`` returns. That is, it doesn't use
+``init`` as a *transformer* function, but rather as an impure initialisation
+routine.
+
+If you want to write a factory function, you'll need to use :func:`Base.derive` and
+invoke the right initialisation routine instead.
View
194 docs/source/api/boo.rst
@@ -0,0 +1,194 @@
+{} boo
+******
+
+
+.. module:: boo
+ :synopsis: Prototypical utilities for Object Orientation / Composition
+ :platform: ECMAScript 5
+
+
+The **boo** module provides primitives that abstract the semantics of
+prototypical object orientation, as implemented by *JavaScript*, such
+that these features can be explored with a more usable interface.
+
+The module provides such features as the stand-alone functions:
+:func:`extend` and :func:`derive`, as well as an Object interface that can be
+extended upon: :class:`Base`.
+
+
+
+Internal
+========
+
+Interfaces
+----------
+
+.. data:: DataObject
+
+ .. code-block:: haskell
+
+ type DataObject :: { "to_data" :: () -> Object }
+
+
+.. data:: Mixin
+
+ .. code-block:: haskell
+
+ type Mixin :: Object | DataObject
+
+
+
+Helpers
+-------
+
+.. function:: copy_property(source, target, property)
+
+ .. code-block:: haskell
+
+ copy_property! :: Object, target:Object*, String -> target
+
+ Copies a property from ``source`` to ``target``.
+
+
+
+.. function:: data_obj_p(subject)
+
+ .. code-block:: haskell
+
+ data_obj? :: Any -> Bool
+
+ Checks if the given subject matches the :obj:`DataObject` interface.
+
+
+
+.. function:: resolve_mixin(object)
+
+ .. code-block:: haskell
+
+ resolve_mixin :: Object -> Object
+
+ Returns the proper mixin for the given ``object``.
+
+
+
+.. function:: fast_extend(object, mixins)
+
+ .. code-block:: haskell
+
+ fast_extend! :: target:Object*, [Mixin] -> target
+
+ Extends the target object with the provided mixins, using a
+ right-most precedence rule — when there's a property conflict, the
+ property defined in the last object wins.
+
+ :obj:`DataObject` instances are properly handled by the
+ :func:`resolve_mixin` function.
+
+
+
+Public
+======
+
+Basic primitives
+----------------
+
+.. function:: extend(target, mixins...)
+ :noindex:
+
+ .. code-block:: haskell
+
+ extend!:: Object*, Mixin... -> Object
+
+ Extends the target object with the provided ``mixins``, using a
+ right-most precedence rule.
+
+ .. rst-class:: detail-link
+
+ :doc:`+ <extend>`
+
+
+.. function:: merge(mixins...)
+ :noindex:
+
+ .. code-block:: haskell
+
+ merge :: Mixin... -> Object
+
+ Creates a new object that merges the provided ``mixins``, using a
+ right-most precedence rule.
+
+ .. rst-class:: detail-link
+
+ :doc:`+ <merge>`
+
+
+.. function:: derive(prototype, mixins...)
+ :noindex:
+
+ .. code-block:: haskell
+
+ derive :: Object, Mixin... -> Object
+
+ Creates a new object inheriting from the given ``prototype`` and
+ extends the new instance with the provided ``mixins``.
+
+ .. rst-class:: detail-link
+
+ :doc:`+ <derive>`
+
+
+
+Root object
+-----------
+
+.. class:: Base
+ :noindex:
+
+ .. code-block:: haskell
+
+ object Base :: { init! :: @this:Object*, Any... -> this
+ make :: @this:Object, Any... -> Object <| this
+ derive :: @this:Object, Any... -> Object <| this
+ }
+
+ The root object for basing all the OOP code. Provides all of
+ *Boo's* primitive combinators in an easy and extensible OOP-way.
+
+ .. rst-class:: detail-link
+
+ :doc:`+ <base>`
+
+
+
+Summary
+=======
+
+.. code-block:: haskell
+
+ -- Interface
+ type DataObject :: { "to_data" :: () -> Object }
+ type Mixin :: Object | DataObject
+
+ -- Internal
+ copy_property! :: Object, target:Object*, String -> target
+ data_obj? :: Any -> Bool
+ resolve_mixin :: Object -> Object
+ fast_extend! :: target:Object*, [Mixin] -> target
+
+ -- Public
+ extend! :: Object*, Mixin... -> Object
+ merge :: Mixin... -> Object
+ derive :: Object, Mixin... -> Object
+ object Base :: { init! :: @this:Object*, Any... -> this
+ make :: @this:Object, Any... -> Object <| this
+ derive :: @this:Object, Any... -> Object <| this
+ }
+
+
+.. toctree::
+ :hidden:
+
+ extend
+ merge
+ derive
+ base
View
72 docs/source/api/derive.rst
@@ -0,0 +1,72 @@
+λ derive()
+**********
+
+.. function:: derive(prototype, sources...)
+ :module: boo
+
+ .. code-block:: haskell
+
+ derive :: Object, (Object | DataObject)... -> Object
+
+ Creates a new object inheriting from the given prototype, and extends
+ the new instance with the provided *mixins*.
+
+
+This function works as a higher-level alternative to the standard
+`Object.create`_ function. Instead of passing an object with property
+descriptors as the second parameter, you may pass any number of plain
+JavaScript objects, which will have their *own enumerable* properties copied
+over to the new instance.
+
+.. code-block:: javascript
+
+ var Person = {
+ say:
+ function(thing) {
+ return this.name + ': ' + thing }
+ }
+
+ var Sophie = boo.derive(Person, {
+ name: 'Sophie'
+ })
+
+ Sophie.say('hello.')
+ // => 'Sophie: hello.'
+
+
+.. _Object.create: https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Object/create
+
+
+Limitations
+===========
+
+``derive`` fills the hole left by ``Object.create`` for the end-user, who does
+not care about setting every one of their properties' flags. As such,
+``derive`` provides a lightweight of creating a new object, setting its
+*[[Prototype]]* slot and initialising it with properties, but doesn't give the
+user any additional power — all properties will be *enumerable*, *configurable* and
+*writable*.
+
+Only *own enumerable* properties from the ``sources`` is copied over, and
+conflict resolution works in the same manner as :doc:`extend()'s <extend>`.
+
+
+Tutorials and examples
+======================
+
+ - `Understanding JavaScript OOP`_ describes JavaScript's particular
+ implementation of Object Orientation — the prototypical model, — which is
+ required to understand the implications of using ``derive``.
+
+ - The :doc:`/user/oo` chapter in the :doc:`Discover Boo </user/index>`
+ reference describes the usage and implications of ``derive`` at length.
+
+
+.. _Understanding JavaScript OOP: http://killdream.github.com/blog/2011/10/understanding-javascript-oop/index.html#sec-3
+
+
+Related functionality
+=====================
+
+:doc:`λ extend() <extend>`
+ The core implementation of ``derive's`` instance initialisation.
View
118 docs/source/api/extend.rst
@@ -0,0 +1,118 @@
+λ extend()
+**********
+
+.. function:: extend(target, sources...)
+ :module: boo
+
+ .. code-block:: haskell
+
+ extend :: Object, (Object | DataObject)... -> Object
+
+ Extends the target object with the provided mixins, using a right-most
+ precedence rule.
+
+This function copies all properties from the given ``sources`` over to the
+``target`` object. It is an impure function, and thus the ``target`` object
+will be modified in-place — if you're looking for a pure alternative, you can
+take a look at :doc:`merge`.
+
+.. code-block:: javascript
+
+ var x = { a: 1, b: 2 }
+ boo.extend(x, { c: 3 })
+ x
+ // => { a: 1, b: 2, c: 3 }
+
+
+Conflict resolution
+===================
+
+If there's any conflict, that is, more than one object defines the same
+property, then the property in the right-most object will be used.
+
+.. code-block:: javascript
+
+ boo.extend({ a: 3, b: 2 }, { a: 2, c: 3 }, { a: 1 })
+ // => { a: 1, b: 2, c: 3 }
+
+
+Data objects
+============
+
+Data objects are handled gracefully by ``extend``, by using the object returned
+by the ``to_data`` method rather than the given object. This means that an
+object can control which values to share, and which values to initialise when
+used as a *mixin*.
+
+.. code-block:: javascript
+
+ var base_collection = { toString: function() {
+ return '(' + this.items.join(' ') + ')' }}
+
+ var coll1 = { items: [ 1, 2, 3 ] }
+ var coll2 = { items: [ 1, 2, 3 ]
+ , to_data: function(){
+ return { items: [] } }}
+
+
+ var instance1 = boo.extend({}, coll1, base_collection)
+ instance1.toString()
+ // => '(1 2 3)'
+ instance1.items.push(4)
+ coll1.items.toString()
+ // => '1, 2, 3, 4'
+
+ var instance2 = boo.extend({}, coll2, base_collection)
+ instance2.toString()
+ // => '()'
+ instance2.items.push(4)
+ coll2.items.toString()
+ // => '1, 2, 3'
+
+
+
+Limitations
+===========
+
+``extend`` will only be able to copy the **own enumerable** properties of the
+source objects, as such, properties that are inherited from a *[[Prototype]]*
+link will not be copied over to the ``target``. Likewise, in newer engines,
+properties that have been declared with a ``non-enumerable`` flag will not be
+copied.
+
+.. code-block:: javascript
+
+ var x = { a: 1 }
+ var y = { a: 2 }
+ var z = { __proto__: x, b: 2 }
+ Object.defineProperty(z, { c: { value: 3, enumerable: false }})
+ boo.extend(y, z)
+
+ // => { a: 2, b: 2 }
+
+While this might be a limiting feature in some cases, specially if you're only
+targeting newer engines, this allows us to maintain full backwards
+compatibility with old engines.
+
+
+Tutorials and examples
+======================
+
+ - `Yay for Sugary JavaScript OO`_ describes how to use ``extend`` and
+ ``merge`` to bring the power of `mixins`_ to JavaScript.
+
+ - The :doc:`/user/mixins` chapter in the :doc:`Discover Boo </user/index>`
+ reference also describes the usage of ``extend`` and ``merge`` for mixins
+ at length.
+
+
+.. _Yay for Sugary JavaScript OO: http://killdream.github.com/blog/2011/11/for-sugary-object-oriented-js/index.html#sec-2-1
+.. _mixins: http://en.wikipedia.org/wiki/Mixin
+
+
+Related functionality
+=====================
+
+:doc:`λ merge() <merge>`
+ a pure alternative to ``extend``, useful if you don't want to modify the
+ ``target`` object.
View
12 docs/source/api/index.rst
@@ -0,0 +1,12 @@
+#############
+API Reference
+#############
+
+This document presents a quick reference of Boo's public API, with use cases
+and examples.
+
+.. toctree::
+ :titlesonly:
+
+ boo
+
View
45 docs/source/api/merge.rst
@@ -0,0 +1,45 @@
+λ merge()
+*********
+
+.. function:: merge(sources...)
+ :module: boo
+
+ .. code-block:: haskell
+
+ merge :: (Object | DataObject)... -> Object
+
+ Creates a new object that merges the provided mixins, using a
+ right-most precedence rule.
+
+This function is mostly a convenience for invoking :doc:`extend()
+<extend>` with an empty object as target. Please see the ``extend``
+documentation for information on the core semantics of ``merge``.
+
+.. code-block:: javascript
+
+ var x = { a: 1 }
+ var y = { b: 2 }
+ var z = boo.merge(x, y)
+ // => { a: 1, b: 2 }
+
+ x
+ // => { a: 1 }
+ y
+ // => { b: 2 }
+
+Limitations
+===========
+
+While being pure — the first object passed into the function won't be
+changed, — it won't preserve properties nor *[[Prototype]]* chains. In
+fact, one could think of ``merge`` as a target-less ``extend``, where
+the result is a brand new object that just gathers properties from a
+range of sources.
+
+
+Related functionality
+=====================
+
+:doc:`λ extend <extend>`
+ ``merge`` is just a convenience for ``extend``. The original function
+ is faster, but impure.
View
6 docs/source/conf.py
@@ -48,9 +48,9 @@
# built documents.
#
# The short X.Y version.
-version = '1.1.0'
+version = '1.2.0'
# The full version, including alpha/beta/rc tags.
-release = '1.1.0'
+release = '1.2.0'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
@@ -91,7 +91,7 @@
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
-html_theme = 'calliope'
+html_theme = 'caffeine'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
View
14 docs/source/index.rst
@@ -22,8 +22,16 @@ Guides
A quick reference on the minimal Boo's API, including plenty of
usage examples and cross-references.
+.. toctree::
+ :hidden:
+
+ user/index
+ api/index
+
+.. index:: installing, downloading
+
Installing
----------
@@ -49,6 +57,8 @@ In the browser, you have to include the script tag pointing to the
+.. index:: platform support
+
Platform Support
----------------
@@ -85,6 +95,8 @@ you.
+.. index:: support, tracker, issues
+
Support
-------
@@ -94,6 +106,8 @@ Boo uses the `Github tracker`_ for tracking bugs and new features.
+.. index:: licence, license
+
Licence
-------
View
4 docs/source/user/clone.rst
@@ -1,7 +1,7 @@
-.. title:: Discover Boo › Clones
+.. index:: clone, derive, delegation, inheritance
Clones
-======
+******
In prototypical object-oriented languages, *cloning* is the act of
making a brand new instance out of another instance, with the same
View
5 docs/source/user/index.rst
@@ -1,13 +1,14 @@
+############
Discover Boo
-============
+############
This document will guide you through the concepts abstracted by the
**Boo** library, so you can leverage them to better structure your
code-base.
Table of Contents
------------------
+=================
.. toctree::
:maxdepth: 2
View
4 docs/source/user/intro.rst
@@ -1,7 +1,5 @@
-.. title:: Discover Boo › Overview
-
Overview
-========
+********
**Boo** is an object orientation library that abstracts the semantics of
prototypical inheritance, as implemented by *JavaScript*, so they can be
View
12 docs/source/user/mixins.rst
@@ -1,7 +1,7 @@
-.. title:: Discover Boo › Mixins
+.. index:: mixin, extend
Mixins
-======
+******
The first level of abstraction defined in **Boo** is carried by mixins,
which we define as parent-less objects that can be copied into other
@@ -31,8 +31,10 @@ However, the ``extend`` method, and those who build upon it have some
particularities that we will discuss in the following sections.
+.. index:: data-objects
+
Data-objects
-''''''''''''
+============
As you should know, if you set an *Object* as the value of a property
slot in JavaScript, that only makes a shallow copy of the *Object*. That
@@ -111,8 +113,10 @@ exposed, by creating a new object::
// => [ ]
+.. index:: conflict resolution
+
Conflict resolution
-'''''''''''''''''''
+===================
When mixing objects in the naivë way, naming conflicts may arise. For
example, if one attempted to merge a self-implemented ``list`` with
View
4 docs/source/user/oo.rst
@@ -1,7 +1,7 @@
-.. title:: Discover Boo › Object Orientation
+.. index:: object orientation, prototypical
Object Orientation
-==================
+******************
The last layer of abstraction defined by ``boo`` is a layer on top of
the previously discussed primitives: :doc:`extend <mixins>` and

0 comments on commit 455f905

Please sign in to comment.