Updates base docs with links.
authordsc <dsc@wikimedia.org>
Thu, 12 Apr 2012 22:20:35 +0000 (15:20 -0700)
committerdsc <dsc@wikimedia.org>
Thu, 12 Apr 2012 22:20:35 +0000 (15:20 -0700)
docs/internals/backbone-base.md

index e5b0bed..ffcfb70 100644 (file)
@@ -1,6 +1,7 @@
 # Backbone Base Classes
 
-Nearly all models, model collections, and views in the project derive from three base classes, aptly named `BaseModel`, `BaseList`, and `BaseView`. Herein we'll discuss some of the more arcane aspects of these classes, especially the default behavior they implement, and the ways in which subclasses can augment it.
+Nearly all models, model collections, and views in the project derive from three base classes, aptly named `BaseModel`, `BaseList`, and `BaseView`, each extending their [Backbone][backbone] counterpart. Herein we'll discuss some of the more arcane aspects of these classes, especially the default behavior they implement, and the ways in which subclasses can augment it.
+
 
 ## Table of Contents
 
@@ -24,7 +25,7 @@ To this end, all Base classes provide methods for this kind of synchronization:
 
 ## BaseModel
 
-`BaseModel` provides two simple but important features: nested lookups and KV-pairs serialization.
+`BaseModel` extends [Backbone.Model](http://backbonejs.org/#Model) to provide two simple but important features: nested lookups and KV-pairs serialization.
 
 ### Nested Attribute Lookup
 
@@ -60,17 +61,24 @@ m = new BaseModel { a:1, b:2, foo:{ bar:3 } }
 m.toKV() is 'a=1&b=2&foo.bar=3'
 ```
 
-The Underscore extensions can be found in `lib/util/underscore`, specifically `kv.co` and `object.co`.
+The [Underscore][underscore] extensions can be found in `lib/util/underscore`, specifically `kv.co` and `object.co`.
 
 
 ## BaseList
 
-`BaseList` mostly exists for completeness -- at present, it merely provides implementations of the KV-Pairs protocol fed by `toJSON()`. This typically has a poor result.
+`BaseList` extends [Backbone.Collection](http://backbonejs.org/#Collection) -- at present, it merely provides implementations of the KV-Pairs protocol fed by `toJSON()`. This typically has a poor result, as you get things like:
+
+```coffee
+list = new BaseList [{ foo:1, bar:2 }]
+list.toKV() is '0.foo=1&0.bar=2'
+```
+
+...Which, while reasonable and correct, is not terribly semantic. We'd probably prefer the collection indices in there to be replaced with `model.id` or `model.cid`, but I was hesitant to be opinionated about something I've never seen a use for.
 
 
 ## BaseView
 
-`BaseView` provides a large number of convenience methods, most of which are simple enough to read about in the source-docs. Instead, we'll focus here on the view lifecycle.
+`BaseView` extends [Backbone.View](http://backbonejs.org/#View) to provide a large number of convenience methods. Many of these are simple enough to read about in the source-docs, so instead, we'll mostly focus here on the view lifecycle.
 
 ### Model Integration
 
@@ -116,3 +124,7 @@ View handling could use a lot of work to eliminate boilerplate and simplify comm
 - Events don't bubble through the view hierarchy as they do with the DOM. This means views must manually inform their subviews to re-render. I left this unimplemented mostly because of the render-vs-update issue above.
 
 
+
+[backbone]: http://backbonejs.org/
+[underscore]: http://underscorejs.org/
+[json]: https://developer.mozilla.org/en/JSON#toJSON()_method