write more documentation

lib/diaspora_federation.rb

@@ -16,6 +16,10 @@ module DiasporaFederation
   )
 
   class << self
+    # {Callbacks} instance with defined callbacks
+    # @see Callbacks#on
+    # @see Callbacks#trigger
+    #
     attr_reader :callbacks
 
     # the pod url
@@ -40,6 +44,14 @@ module DiasporaFederation
       yield self
     end
 
+    # define the callbacks
+    #
+    # @example
+    #   config.define_callbacks do
+    #     on :some_event do |arg1|
+    #       # do something
+    #     end
+    #   end
     def define_callbacks(&block)
       @callbacks.instance_eval(&block)
     end

lib/diaspora_federation/callbacks.rb

@@ -1,10 +1,27 @@
 module DiasporaFederation
+  # Callbacks are used to communicate with the application. They are called to
+  # fetch data and after data is received.
   class Callbacks
+    # Initializes a new Callbacks object with the event-keys that need to be defined.
+    #
+    # @example
+    #   Callbacks.new %i(
+    #     some_event
+    #     another_event
+    #   )
+    #
+    # @param [Hash] events event keys
     def initialize(events)
       @events   = events
       @handlers = {}
     end
 
+    # defines a callback
+    #
+    # @example
+    #   callbacks.on :some_event do |arg1|
+    #     # do something
+    #   end
     def on(event, &callback)
       raise ArgumentError, "Undefined event #{event}" unless @events.include? event
       raise ArgumentError, "Already defined event #{event}" if @handlers.has_key? event
@@ -12,16 +29,26 @@ module DiasporaFederation
       @handlers[event] = callback
     end
 
+    # triggers a callback
+    #
+    # @example
+    #   callbacks.trigger :some_event, "foo"
+    #
+    # @return [Object] the return-value of the callback
     def trigger(event, *args)
       raise ArgumentError, "Undefined event #{event}" unless @events.include? event
 
       @handlers[event].call(*args)
     end
 
+    # checks if all callbacks are defined
+    # @return [Boolean]
     def definition_complete?
       missing_handlers.empty?
     end
 
+    # Returns all undefined callbacks
+    # @return [Hash] callback keys
     def missing_handlers
       @events - @handlers.keys
     end

lib/diaspora_federation/properties_dsl.rb

@@ -1,8 +1,15 @@
 module DiasporaFederation
   # Provides a simple DSL for specifying {Entity} properties during class
   # definition.
+  #
+  # @example
+  #   property :prop
+  #   property :optional, default: false
+  #   property :dynamic_default, default: -> { Time.now }
+  #   entity :nested, NestedEntity
+  #   entity :multiple, [OtherEntity]
   module PropertiesDSL
-    # @return [Hash] hash of declared entity properties
+    # @return [Array<Hash>] hash of declared entity properties
     def class_props
       @class_props ||= []
     end
@@ -31,22 +38,28 @@ module DiasporaFederation
     end
 
     # Return array of missing required property names
+    # @return [Array<Symbol>] missing required property names
     def missing_props(args)
       class_prop_names - default_props.keys - args.keys
     end
 
     # Return a new hash of default values, with dynamic values
     # resolved on each call
+    # @return [Hash] default values
     def default_values
       default_props.each_with_object({}) { |(name, prop), hash|
         hash[name] = prop.respond_to?(:call) ? prop.call : prop
       }
     end
 
+    # Returns all nested Entities
+    # @return [Array<Hash>] nested properties
     def nested_class_props
       @nested_class_props ||= class_props.select {|p| p[:type] != String }
     end
 
+    # Returns all property names
+    # @return [Array] property names
     def class_prop_names
       @class_prop_names ||= class_props.map {|p| p[:name] }
     end
@@ -62,10 +75,14 @@ module DiasporaFederation
       instance_eval { attr_reader name }
     end
 
+    # checks if the name is a +Symbol+ or a +String+
+    # @return [Boolean]
     def name_valid?(name)
       name.instance_of?(Symbol) || name.instance_of?(String)
     end
 
+    # checks if the type extends {Entity}
+    # @return [Boolean]
     def type_valid?(type)
       [type].flatten.all? { |type|
         type.respond_to?(:ancestors) && type.ancestors.include?(Entity)