more documentation for validation

lib/diaspora_federation/entities/person.rb

@@ -1,6 +1,8 @@
 module DiasporaFederation
   module Entities
     # this entity contains the base data of a person
+    #
+    # @see Validators::PersonValidator
     class Person < Entity
       # @!attribute [r] guid
       #   @see HCard#guid

lib/diaspora_federation/entities/profile.rb

@@ -1,6 +1,8 @@
 module DiasporaFederation
   module Entities
     # this entity contains all the profile data of a person
+    #
+    # @see Validators::ProfileValidator
     class Profile < Entity
       # @!attribute [r] diaspora_id
       #   The diaspora ID of the person

lib/diaspora_federation/entity.rb

@@ -38,6 +38,12 @@ module DiasporaFederation
     # Initializes the Entity with the given attribute hash and freezes the created
     # instance it returns.
     #
+    # After creation, the entity is validated against a Validator, if one is defined.
+    # The Validator needs to be in the {DiasporaFederation::Validators} namespace and
+    # named like "<EntityName>Validator". Only valid entities can be created.
+    #
+    # @see DiasporaFederation::Validators
+    #
     # @note Attributes not defined as part of the class definition ({PropertiesDSL#property},
     #       {PropertiesDSL#entity}) get discarded silently.
     #

lib/diaspora_federation/validators.rb

@@ -23,6 +23,9 @@ require "diaspora_federation/validators/rules/tag_count"
 
 module DiasporaFederation
   # Validators to perform basic sanity-checks on {DiasporaFederation::Entities federation entities}.
+  #
+  # The Validators are mapped with the entities by name. The naming schema
+  # is "<EntityName>Validator".
   module Validators
   end
 end

lib/diaspora_federation/validators/person_validator.rb

@@ -1,5 +1,6 @@
 module DiasporaFederation
   module Validators
+    # This validates a {Entities::Person}
     class PersonValidator < Validation::Validator
       include Validation
 

lib/diaspora_federation/validators/profile_validator.rb

@@ -1,5 +1,6 @@
 module DiasporaFederation
   module Validators
+    # This validates a {Entities::Profile}
     class ProfileValidator < Validation::Validator
       include Validation
 

lib/diaspora_federation/validators/rules/birthday.rb

@@ -2,11 +2,20 @@ require "date"
 
 module Validation
   module Rule
+    # Birthday validation rule
+    #
+    # Valid is:
+    # * nil or an empty +String+
+    # * a +Date+ object
+    # * a +String+ with the format "yyyy-mm-dd" and is a valid +Date+, example: 2015-07-25
     class Birthday
+      # The error key for this rule
+      # @return [Symbol] error key
       def error_key
         :birthday
       end
 
+      # Determines if value is a valid birthday date
       def valid_value?(value)
         return true if value.nil? || (value.is_a?(String) && value.empty?)
         return true if value.is_a? Date
@@ -20,6 +29,7 @@ module Validation
       end
 
       # This rule has no params
+      # @return [Hash] params
       def params
         {}
       end

lib/diaspora_federation/validators/rules/boolean.rb

@@ -1,10 +1,19 @@
 module Validation
   module Rule
+    # Boolean validation rule
+    #
+    # Valid is:
+    # * a +String+: "true", "false", "t", "f", "yes", "no", "y", "n", "1", "0"
+    # * a +Fixnum+: 1 or 0
+    # * a +Boolean+: true or false
     class Boolean
+      # The error key for this rule
+      # @return [Symbol] error key
       def error_key
         :boolean
       end
 
+      # Determines if value is a valid +boolean+
       def valid_value?(value)
         return false if value.nil?
 
@@ -20,6 +29,7 @@ module Validation
       end
 
       # This rule has no params
+      # @return [Hash] params
       def params
         {}
       end

lib/diaspora_federation/validators/rules/diaspora_id.rb

@@ -5,6 +5,7 @@ module Validation
     # This rule is based on https://github.com/zombor/Validator/blob/master/lib/validation/rule/email.rb
     # which was adapted from https://github.com/emmanuel/aequitas/blob/master/lib/aequitas/rule/format/email_address.rb
     class DiasporaId
+      # The Regex for a valid diaspora ID
       DIASPORA_ID = begin
         letter         = "a-zA-Z"
         digit          = "0-9"
@@ -25,16 +26,18 @@ module Validation
       end
 
       # The error key for this rule
+      # @return [Symbol] error key
       def error_key
         :diaspora_id
       end
 
-      # Determines if value is a valid email
+      # Determines if value is a valid diaspora ID
       def valid_value?(value)
         !DIASPORA_ID.match(value).nil?
       end
 
       # This rule has no params
+      # @return [Hash] params
       def params
         {}
       end

lib/diaspora_federation/validators/rules/guid.rb

@@ -1,15 +1,25 @@
 module Validation
   module Rule
+    # GUID validation rule
+    #
+    # Valid is a +String+ that is at least 16 chars long and contains only:
+    # * Letters: a-z
+    # * Numbers: 0-9
+    # * Special chars: '-', '_', '@', '.' and ':'
     class Guid
+      # The error key for this rule
+      # @return [Symbol] error key
       def error_key
         :guid
       end
 
+      # Determines if value is a valid +GUID+
       def valid_value?(value)
         value.is_a?(String) && value.downcase =~ /\A[0-9a-z\-_@.:]{16,}\z/
       end
 
       # This rule has no params
+      # @return [Hash] params
       def params
         {}
       end

lib/diaspora_federation/validators/rules/not_nil.rb

@@ -1,15 +1,20 @@
 module Validation
   module Rule
+    # Validates that a property is not +nil+
     class NotNil
+      # The error key for this rule
+      # @return [Symbol] error key
       def error_key
         :not_nil
       end
 
+      # Determines if value is not nil
       def valid_value?(value)
         !value.nil?
       end
 
       # This rule has no params
+      # @return [Hash] params
       def params
         {}
       end

lib/diaspora_federation/validators/rules/public_key.rb

@@ -1,11 +1,19 @@
 module Validation
   module Rule
+    # Public key validation rule
+    #
+    # A valid key must:
+    # * start with "-----BEGIN PUBLIC KEY-----" and end with "-----END PUBLIC KEY-----"
+    # or
+    # * start with "-----BEGIN RSA PUBLIC KEY-----" and end with "-----END RSA PUBLIC KEY-----"
     class PublicKey
+      # The error key for this rule
+      # @return [Symbol] error key
       def error_key
         :public_key
       end
 
-      # allow both "PUBLIC KEY" and "RSA PUBLIC KEY"
+      # Determines if value is a valid public key
       def valid_value?(value)
         (value.strip.start_with?("-----BEGIN PUBLIC KEY-----") &&
          value.strip.end_with?("-----END PUBLIC KEY-----")) ||
@@ -14,6 +22,7 @@ module Validation
       end
 
       # This rule has no params
+      # @return [Hash] params
       def params
         {}
       end

lib/diaspora_federation/validators/rules/tag_count.rb

@@ -2,7 +2,10 @@ module Validation
   module Rule
     # Rule for validating the number of tags in a string.
     # Only the "#" characters will be counted.
+    # The string can be nil.
     class TagCount
+      # This rule must have a +maximum+ param
+      # @return [Hash] params
       attr_reader :params
 
       # @param [Hash] params
@@ -15,10 +18,13 @@ module Validation
         @params = params
       end
 
+      # The error key for this rule
+      # @return [Symbol] error key
       def error_key
         :tag_count
       end
 
+      # Determines if value doesn't have more than +maximum+ tags
       def valid_value?(value)
         value.nil? || value.count("#") <= params[:maximum]
       end