more documentation

README.md

@@ -1,6 +1,6 @@
 # diaspora* federation library
 
-**a library that provides functionalities needed for the diaspora* federation protocol**
+**A library that provides functionalities needed for the diaspora* federation protocol**
 
 [![Build Status](https://travis-ci.org/SuperTux88/diaspora_federation.svg?branch=master)](https://travis-ci.org/SuperTux88/diaspora_federation)
 [![Code Climate](https://codeclimate.com/github/SuperTux88/diaspora_federation/badges/gpa.svg)](https://codeclimate.com/github/SuperTux88/diaspora_federation)
@@ -57,7 +57,7 @@ After the first stable release, this repo will be moved to the [diaspora organiz
 
 ## Diaspora
 
-a privacy-aware, distributed, open source social network
+A privacy-aware, distributed, open source social network
 
 Links:
 [Project site](https://diasporafoundation.org) |

lib/diaspora_federation.rb

@@ -52,6 +52,8 @@ module DiasporaFederation
     #       # do something
     #     end
     #   end
+    #
+    # @param [Proc] block the callbacks to define
     def define_callbacks(&block)
       @callbacks.instance_eval(&block)
     end

lib/diaspora_federation/callbacks.rb

@@ -22,6 +22,10 @@ module DiasporaFederation
     #   callbacks.on :some_event do |arg1|
     #     # do something
     #   end
+    #
+    # @param [Symbol] event the event key
+    # @param [Proc] callback the callback block
+    # @raise [ArgumentError] if the event key is undefined or has already a handler
     def on(event, &callback)
       raise ArgumentError, "Undefined event #{event}" unless @events.include? event
       raise ArgumentError, "Already defined event #{event}" if @handlers.has_key? event
@@ -34,7 +38,9 @@ module DiasporaFederation
     # @example
     #   callbacks.trigger :some_event, "foo"
     #
+    # @param [Symbol] event the event key
     # @return [Object] the return-value of the callback
+    # @raise [ArgumentError] if the event key is undefined
     def trigger(event, *args)
       raise ArgumentError, "Undefined event #{event}" unless @events.include? event
 

lib/diaspora_federation/properties_dsl.rb

@@ -76,12 +76,14 @@ module DiasporaFederation
     end
 
     # checks if the name is a +Symbol+ or a +String+
+    # @param [String, Symbol] name the name to check
     # @return [Boolean]
     def name_valid?(name)
       name.instance_of?(Symbol) || name.instance_of?(String)
     end
 
     # checks if the type extends {Entity}
+    # @param [Class] type the type to check
     # @return [Boolean]
     def type_valid?(type)
       [type].flatten.all? { |type|