improve documentation

lib/diaspora_federation.rb

@@ -61,16 +61,16 @@ module DiasporaFederation
     #   config.certificate_authorities = AppConfig.environment.certificate_authorities.get
     attr_accessor :certificate_authorities
 
-    # Maximum number of parallel HTTP requests made to other pods
+    # Maximum number of parallel HTTP requests made to other pods (default: +20+)
     #
     # @example
     #   config.http_concurrency = AppConfig.settings.typhoeus_concurrency.to_i
     attr_accessor :http_concurrency
 
-    # timeout in seconds for http-requests
+    # timeout in seconds for http-requests (default: +30+)
     attr_accessor :http_timeout
 
-    # Turn on extra verbose output when sending stuff.
+    # Turn on extra verbose output when sending stuff. (default: +false+)
     #
     # @example
     #   config.http_verbose = AppConfig.settings.typhoeus_verbose?

lib/diaspora_federation/entities/message.rb

@@ -34,6 +34,8 @@ module DiasporaFederation
       #   @return [String] conversation guid
       property :conversation_guid
 
+      # The {Message} parent is a {Conversation}
+      # @return [String] parent entity type
       def self.get_target_entity_type(*)
         "Conversation"
       end

lib/diaspora_federation/entities/poll_participation.rb

@@ -24,6 +24,8 @@ module DiasporaFederation
       #   @return [String] poll answer guid
       property :poll_answer_guid
 
+      # The {PollParticipation} parent is a {Poll}
+      # @return [String] parent entity type
       def self.get_target_entity_type(*)
         "Poll"
       end

lib/diaspora_federation/entities/relayable.rb

@@ -32,6 +32,8 @@ module DiasporaFederation
           property :parent_author_signature, default: nil
           property :author_signature, default: nil
 
+          # get the type of the parent entity
+          # @return [String] parent entity type
           def self.get_target_entity_type(data)
             data[:target_type] || "Post"
           end
@@ -57,6 +59,7 @@ module DiasporaFederation
 
       # verifies the signatures (+author_signature+ and +parent_author_signature+ if needed)
       # @param [Hash] data hash with data to verify
+      # @param [Class] klass entity type
       # @raise [SignatureVerificationFailed] if the signature is not valid or no public key is found
       def self.verify_signatures(data, klass)
         pubkey = DiasporaFederation.callbacks.trigger(:fetch_public_key_by_diaspora_id, data[:diaspora_id])
@@ -75,6 +78,7 @@ module DiasporaFederation
 
       # this happens only on downstream federation
       # @param [Hash] data hash with data to verify
+      # @param [Class] klass entity type
       def self.verify_parent_signature(data, klass)
         pubkey = DiasporaFederation.callbacks.trigger(
           :fetch_author_public_key_by_entity_guid,
@@ -93,6 +97,7 @@ module DiasporaFederation
       # if the signatures are not in the hash yet and if the keys are available.
       #
       # @param [Hash] data hash given for a signing
+      # @param [Class] klass entity type
       def self.update_signatures!(data, klass)
         if data[:author_signature].nil?
           privkey = DiasporaFederation.callbacks.trigger(:fetch_private_key_by_diaspora_id, data[:diaspora_id])

lib/diaspora_federation/federation/receiver.rb

@@ -4,10 +4,13 @@ module DiasporaFederation
     #   @see Receiver::Public
     #   @see Receiver::Private
     class Receiver
+      # initializes a new Receiver for a salmon XML
+      # @param [String] salmon_xml the message salmon xml
       def initialize(salmon_xml)
         @salmon_xml = salmon_xml
       end
 
+      # Parse the salmon xml and send it to the +:save_entity_after_receive+ callback
       def receive!
         sender_id = slap.author_id
         public_key = DiasporaFederation.callbacks.trigger(:fetch_public_key_by_diaspora_id, sender_id)

lib/diaspora_federation/federation/receiver/private.rb

@@ -4,6 +4,9 @@ module DiasporaFederation
       # Receiver::Private is used to receive private messages, which are addressed
       # to a specific user, encrypted with his public key and packed using Salmon::EncryptedSlap
       class Private < Receiver
+        # initializes a new Private Receiver for a salmon XML
+        # @param [String] salmon_xml the message salmon xml
+        # @param [OpenSSL::PKey::RSA] recipient_private_key recipient private key to decrypt the message
         def initialize(salmon_xml, recipient_private_key)
           super(salmon_xml)
           raise RecipientKeyNotFound if recipient_private_key.nil?
@@ -12,6 +15,8 @@ module DiasporaFederation
 
         protected
 
+        # parses the encrypted slap xml
+        # @return [Salmon::EncryptedSlap] slap instance
         def slap
           @salmon ||= Salmon::EncryptedSlap.from_xml(@salmon_xml, @recipient_private_key)
         end

lib/diaspora_federation/federation/receiver/public.rb

@@ -6,6 +6,8 @@ module DiasporaFederation
       class Public < Receiver
         protected
 
+        # parses the public slap xml
+        # @return [Salmon::Slap] slap instance
         def slap
           @salmon ||= Salmon::Slap.from_xml(@salmon_xml)
         end

lib/diaspora_federation/test/factories.rb

@@ -3,7 +3,9 @@ require "factory_girl"
 
 module DiasporaFederation
   module Test
+    # Factories for federation entities
     module Factories
+      # defines the federation entity factories
       def self.federation_factories
         FactoryGirl.define do
           initialize_with { new(attributes) }