sprinkle a little documentation around lib, mostly just specifying return types

app/models/post_visibility.rb

@@ -3,18 +3,21 @@
 #   the COPYRIGHT file.
 
 class PostVisibility < ActiveRecord::Base
+
   belongs_to :contact
   belongs_to :post
 
-
+  # Perform a batch import, given a set of contacts and a post
+  # @note performs a bulk insert in mySQL; performs linear insertions in postgres
+  # @param contacts [Array<Contact>] Recipients
+  # @param post [Post]
+  # @return [void]
   def self.batch_import(contacts, post)
     if postgres?
-      # Take the naive approach to inserting our new visibilities for now.
       contacts.each do |contact|
         PostVisibility.find_or_create_by_contact_id_and_post_id(contact.id, post.id)
       end
     else
-      # Use a batch insert on mySQL.
       new_post_visibilities = contacts.map do |contact|
         PostVisibility.new(:contact_id => contact.id, :post_id => post.id)
       end

app/models/profile.rb

@@ -127,7 +127,7 @@ class Profile < ActiveRecord::Base
   end
 
   # Constructs a full name by joining #first_name and #last_name
-  # @returns [String] A full name
+  # @return [String] A full name
   def construct_full_name
     self.full_name = [self.first_name, self.last_name].join(' ').downcase
     self.full_name

lib/aspect_stream.rb

@@ -54,6 +54,7 @@ class AspectStream
     @people ||= Person.all_from_aspects(aspect_ids, @user)
   end
 
+  # The first aspect in #aspects, given the stream is not for all aspects, or #aspects size is 1
   # @note aspects.first is used for mobile. NOTE(this is a hack and should be fixed)
   # @return [Aspect,Symbol]
   def aspect

lib/postzord/receiver/local_post_batch.rb

@@ -16,28 +16,36 @@ module Postzord
         notify_users
       end
 
+      # Batch import visibilities for the recipients of the given @post
+      # @note performs a bulk insert into mySQL
+      # @return [void]
       def create_visibilities
         contacts = Contact.where(:user_id => @recipient_user_ids, :person_id => @post.author_id)
         PostVisibility.batch_import(contacts, post)
       end
 
+      # Issue websocket requests to all specified recipients
+      # @return [void]
       def socket_to_users
         @users.each do |user|
           @post.socket_to_user(user)
         end
       end
 
+      # Notify any mentioned users within the @post's text
+      # @return [void]
       def notify_mentioned_users
         @post.mentions.each do |mention|
           mention.notify_recipient
         end
       end
 
+      # Notify users of the new post
+      # return [void]
       def notify_users
-        if @post.respond_to?(:notification_type) 
-          @users.each do |user|
-            Notification.notify(user, @post, @post.author)
-          end
+        return unless @post.respond_to?(:notification_type) 
+        @users.each do |user|
+          Notification.notify(user, @post, @post.author)
         end
       end
     end

lib/postzord/receiver/private.rb

@@ -43,7 +43,6 @@ module Postzord
         obj
       end
 
-
       protected
       def salmon
         @salmon ||= Salmon::EncryptedSlap.from_xml(@salmon_xml, @user)

lib/postzord/receiver/public.rb

@@ -29,6 +29,7 @@ module Postzord
         end
       end
 
+      # @return [Object]
       def receive_relayable
         if @object.parent.author.local?
           # receive relayable object only for the owner of the parent object
@@ -37,6 +38,7 @@ module Postzord
         # notify everyone who can see the parent object
         receiver = Postzord::Receiver::LocalPostBatch.new(nil, self.recipient_user_ids)
         receiver.notify_users
+        @object
       end
 
       # @return [Object]
@@ -51,9 +53,9 @@ module Postzord
         User.all_sharing_with_person(@author).select('users.id').map!{ |u| u.id }
       end
 
-      class RelayableObjectWithoutParent < StandardError ; ; end
       private
 
+      # @return [Boolean]
       def object_can_be_public_and_it_is_not?
         @object.respond_to?(:public) && !@object.public?
       end

lib/salmon/encrypted_slap.rb

@@ -4,6 +4,9 @@
 
 module Salmon
   class EncryptedSlap < Slap
+
+    # Construct an encrypted header
+    # @return [String] Header XML
     def header(person)
       <<XML
         <encrypted_header>
@@ -12,16 +15,21 @@ module Salmon
 XML
     end
 
+    # Decrypts an encrypted magic sig envelope
+    # @param key_hash [Hash] Contains 'key' (aes) and 'iv' values
+    # @param user [User]
     def parse_data(key_hash, user)
       user.aes_decrypt(super, key_hash)
     end
 
+    # Decrypts and parses out the salmon header
     # @return [Nokogiri::Doc]
     def salmon_header(doc, user)
       header = user.decrypt(doc.search('encrypted_header').text)
       Nokogiri::XML(header)
     end
 
+    # Encrypt the magic sig
     # @return [String]
     def self.payload(activity, user, aes_key_hash)
       user.person.aes_encrypt(activity, aes_key_hash)

lib/salmon/magic_sig_envelope.rb

@@ -4,7 +4,10 @@
 
 module Salmon
   class MagicSigEnvelope
+
     attr_accessor :data, :data_type, :encoding, :alg, :sig, :author
+
+    # @return [MagicSigEnvelope]
     def self.parse(doc)
       env = self.new
       ns = {'me'=>'http://salmon-protocol.org/ns/magic-env'}
@@ -27,6 +30,7 @@ module Salmon
       env
     end
 
+    # @return [MagicSigEnvelope]
     def self.create(user, activity)
       env = MagicSigEnvelope.new
       env.author = user.person
@@ -42,10 +46,12 @@ module Salmon
       env
     end
 
+    # @return [String]
     def signable_string
       [@data, Base64.urlsafe_encode64(@data_type),Base64.urlsafe_encode64(@encoding),  Base64.urlsafe_encode64(@alg)].join(".")
     end
 
+    # @return [String]
     def to_xml
       <<ENTRY
 <me:env xmlns:me="http://salmon-protocol.org/ns/magic-env">
@@ -57,14 +63,17 @@ module Salmon
 ENTRY
     end
 
+    # @return [String]
     def get_encoding
       'base64url'
     end
 
+    # @return [String]
     def get_data_type
       'application/atom+xml'
     end
 
+    # @return [String]
     def get_alg
       'RSA-SHA256'
     end

lib/salmon/slap.rb

@@ -46,7 +46,6 @@ module Salmon
       slap
     end
 
-
     # @return [String]
     def self.payload(activity, user=nil, aes_key_hash=nil)
       activity
@@ -62,6 +61,7 @@ module Salmon
       doc.search('header')
     end
 
+    # @return [String] The constructed salmon, given a person
     def xml_for(person)
       xml =<<ENTRY
     <?xml version='1.0' encoding='UTF-8'?>
@@ -72,10 +72,14 @@ module Salmon
 ENTRY
     end
 
+    # Wraps plaintext header in <header></header> tags
+    # @return [String] Header XML
     def header(person)
       "<header>#{plaintext_header}</header>"
     end
 
+    # Generate a plaintext salmon header (unencrypted), sans <header></header> tags
+    # @return [String] Header XML (sans <header></header> tags)
     def plaintext_header
       header =<<HEADER
     <iv>#{iv}</iv>
@@ -87,6 +91,7 @@ ENTRY
 HEADER
     end
 
+    # @return [Person] Author of the salmon object
     def author
       if @author.nil?
         @author ||= Person.by_account_identifier @author_email