added comments

app/controllers/roles_controller.rb

@@ -5,12 +5,17 @@ def show
     @role = Role.find(params[:id])
   end
 
+  # Requires that the params :movie_id and :actor_id be set.
+  # Since a role is a relationship, it does not make sense
+  # to create one without knowing the movie and actor.
   def new
     @movie = Movie.find(params[:movie_id])
     @actor = Actor.find(params[:actor_id])
     @role = Role.new
   end
 
+  # Requires that the params :movie_id and :actor_id be set,
+  # just like Role#new.  See above.
   def create
     @movie = Movie.find(params[:movie_id])
     @actor = Actor.find(params[:actor_id])

app/models/actor.rb

@@ -4,5 +4,22 @@ class Actor < Neo4j::Model
   property :name
   property :born
 
+  # The has_n method declares a relationship between Actors and Movies.
+  # It defines convenience methods:
+  # @actor.movies returns an array of movies.
+  # @actor.movies_rels returns an array of the Relationships connecting @actor to the movies.
+  #
+  # === Example
+  #
+  #   humphrey = Actor.new(:name => 'Humphrey Bogart')
+  #   african_queen = Movie.new(:title => 'The African Queen')
+  #   humphrey.movies << african_queen
+  #   humphrey.save
+  #
+  #   humphrey.movies.first.title  # => 'The African Queen'
+  #
+  #   humphrey.movies_rels.first.class # => Role
+  #
+  # Here we specify that the relationship will be an instance of the Role class.
   has_n(:roles).to(Movie).relationship(Role)
 end

app/models/movie.rb

@@ -4,15 +4,22 @@ class Movie < Neo4j::Model
   property :title
   property :year
 
-  # The following line lets you create relationships between Actors and Movies.
+  # The has_n method declares a relationship between Actors and Movies.
+  # It defines convenience methods:
+  # @movie.actors returns an array of actors.
+  # @movie.actors_rels returns an array of the Relationships connecting @movie to the actors.
   #
   # === Example
   #
   #   humphrey = Actor.new(:name => 'Humphrey Bogart')
   #   m = Movie.new(:title => 'The African Queen')
   #   m.actors << humphrey
   #   m.save
-  #   m.actors.first  # => returns humphrey
   #
+  #   m.actors.first  # => humphrey
+  #
+  #   m.actors_rels.first # 
+  #
+  # Here we specify that the relationship will be an instance of the Role class.
   has_n(:actors).from(Actor, :roles).relationship(Role)
 end

app/models/role.rb

@@ -1,3 +1,13 @@
+# A Role is a relationship between an Actor and a Movie.
+# 
+# === To make a new Role, do this
+#
+#   @actor = Actor.create( ... )
+#   @movie = Movie.create( ... )
+#   role_params = {:as => 'Captain Haddock'}
+#   @role = @actor.roles_rels.connect(@movie, role_params)
+#   @role.save
+#
 class Role < Neo4j::Rails::Relationship
   property :as
 

config/routes.rb

@@ -3,12 +3,14 @@
 
   resources :actors do
     member do
+      # Lets you pick a movie to associate with this actor.
       get :add_role
     end
   end
 
   resources :movies do
     member do
+      # Lets you pick an actor to associate with this movie.
       get :add_role
     end
   end