tgriesser/bookshelf — pull request #364 by wbyoung (2014-05-22 04:58:32+00:00)
Title: Documentation Changes

This is a followup pull request for #346.

I did a bit of digging on how other people are using terminology to explain relations/associations. Unfortunately, I think this is one of those cases where terminology is used somewhat inconsistently.

This is my attempt to improve the way Bookshelf is explaining associations.

I've used a few ORM tools in the past (Rails & Django most heavily). I know Bookshelf is young, but in trying to get up and running, I spent a little too much time hunting through the docs and trying to piece things together. With background in other tools, I expected to be able to get started a little faster with Bookshelf. I also made assumptions based on my Rails background on how things should work. Some of these assumptions were correct, some incorrect.

I think we can do better on giving examples of how to use things. In that light, this is a first pass at adding some more examples as well as clearing up `belongsTo`.

Oh, and I threw in `highlight.js`. Sorry to wrap it in one pull request. I'll happily split it up into two if you want, but the highlight stuff touches code I added in the first commit, too.

**Findings**

I found [this .NET framework article](http://msdn.microsoft.com/en-us/library/vstudio/ee382826(v=vs.100).aspx) to be a good starting place for associations and defining what may be slightly more proper language to discuss associations including using _multiplicity_ to describe how many things each end of a relationship has. I think this would be overkill for Bookshelf, but I think it's still a good reference.

Rails [documents `belongs_to`](http://guides.rubyonrails.org/association_basics.html#the-belongs-to-association) as a one-to-one association. I find this confusing in their docs as well, but they do a better job of illustrating that `belongs_to` is used with `has_many`, or many-to-many, relationships as well. So while the word choice isn't consistent with the way it seems to be used in database modeling, their examples make it very clear.

Django simply discusses relationships by discussing foreign keys. They have `OneToOneField`, `ForeignKey`, and `ManyToManyField` options. Each clearly maps to one type of relationship, and a single field definition handles both sides of the relationships. From their docs:

> Other object-relational mappers require you to define relationships on both sides. The Django developers believe this is a violation of the DRY (Don’t Repeat Yourself) principle, so Django only requires you to define the relationship on one end.

Hibernate discusses [one-to-one and one-to-many basically at the same time](http://docs.jboss.org/hibernate/orm/4.3/manual/en-US/html_single/#d5e3678) since they're so closely related.

[SQLAlchemy's docs](http://docs.sqlalchemy.org/en/rel_0_9/orm/relationships.html) are bit more difficult to understand, and I haven't used it before, but the wording and examples they use are consistent with other ORMs in terms of one-to-one and one-to-many relationships. They clearly give examples for how to set up each type and where that minor distinguishing factor comes in that makes a one-to-one something different (in their case `uselist=False`). This is the only tool I've seen that actually distinguishes between one-to-many and many-to-one relationships (though a quick search turn up [at least one Stack Overflow question](http://stackoverflow.com/questions/4601703/difference-between-one-to-many-and-many-to-one-relationship) and [another library that provides methods for both](http://docs.oracle.com/javaee/6/api/javax/persistence/ManyToOne.html)).

Any feedback/suggestions from @bendrucker or @ricardograca would be welcome as well.