Docmented need for include_person option in ActivityLogger

app/models/comment.rb

@@ -15,6 +15,8 @@
 class Comment < ActiveRecord::Base
   include ActivityLogger
 
+  attr_accessor :commented_person
+
   belongs_to :commentable, :polymorphic => true
   belongs_to :commenter, :class_name => "Person",
                          :foreign_key => "commenter_id"
@@ -45,12 +47,12 @@ def blog_post_comment?
     # For example, for blog post comments it's the blog's person
     # For wall comments, it's the person himself.
     def commented_person
-      case commentable.class.to_s
-      when "Person"
-        commentable
-      when "BlogPost"
-        commentable.blog.person
-      end
+      @commented_person ||= case commentable.class.to_s
+                            when "Person"
+                              commentable
+                            when "BlogPost"
+                              commentable.blog.person
+                            end
     end
 
     def log_activity

lib/activity_logger.rb

@@ -1,4 +1,15 @@
 module ActivityLogger
+
+  # Add an activity to the feeds of a person's contacts.
+  # Usually, we only add to the feeds of the contacts, not the person himself.
+  # For example, if a person makes a forum post, the activity shows up in
+  # his contacts' feeds but not his.
+  # The :include_person option is to handle the case when add_activities
+  # should include the person as well.  This happens when
+  # someone comments on a person's blog post or wall.  In that case, when
+  # adding activities to the contacts of the wall's or post's owner,
+  # we should include the owner as well, so that he see's in his feed
+  # that a comment has been made.
   def add_activities(options = {})
     person = options[:person]
     include_person = options[:include_person]