From dd6b938f2ea94604c1635283caf3569ce76b29b0 Mon Sep 17 00:00:00 2001
From: Benjamin Neff <benjamin@coding4coffee.ch>
Date: Sun, 26 Jul 2015 01:19:09 +0200
Subject: [PATCH] more documentation for validation

---
 lib/diaspora_federation/entities/person.rb            |  2 ++
 lib/diaspora_federation/entities/profile.rb           |  2 ++
 lib/diaspora_federation/entity.rb                     |  6 ++++++
 lib/diaspora_federation/validators.rb                 |  3 +++
 .../validators/person_validator.rb                    |  1 +
 .../validators/profile_validator.rb                   |  1 +
 lib/diaspora_federation/validators/rules/birthday.rb  | 10 ++++++++++
 lib/diaspora_federation/validators/rules/boolean.rb   | 10 ++++++++++
 .../validators/rules/diaspora_id.rb                   |  5 ++++-
 lib/diaspora_federation/validators/rules/guid.rb      | 10 ++++++++++
 lib/diaspora_federation/validators/rules/not_nil.rb   |  5 +++++
 .../validators/rules/public_key.rb                    | 11 ++++++++++-
 lib/diaspora_federation/validators/rules/tag_count.rb |  6 ++++++
 13 files changed, 70 insertions(+), 2 deletions(-)

diff --git a/lib/diaspora_federation/entities/person.rb b/lib/diaspora_federation/entities/person.rb
index ebbcbcc..32a9080 100644
--- a/lib/diaspora_federation/entities/person.rb
+++ b/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
diff --git a/lib/diaspora_federation/entities/profile.rb b/lib/diaspora_federation/entities/profile.rb
index c819cff..3a728b8 100644
--- a/lib/diaspora_federation/entities/profile.rb
+++ b/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
diff --git a/lib/diaspora_federation/entity.rb b/lib/diaspora_federation/entity.rb
index 1d01224..86f980b 100644
--- a/lib/diaspora_federation/entity.rb
+++ b/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.
     #
diff --git a/lib/diaspora_federation/validators.rb b/lib/diaspora_federation/validators.rb
index 79d6f40..416e992 100644
--- a/lib/diaspora_federation/validators.rb
+++ b/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
diff --git a/lib/diaspora_federation/validators/person_validator.rb b/lib/diaspora_federation/validators/person_validator.rb
index 33c9957..1995b21 100644
--- a/lib/diaspora_federation/validators/person_validator.rb
+++ b/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
 
diff --git a/lib/diaspora_federation/validators/profile_validator.rb b/lib/diaspora_federation/validators/profile_validator.rb
index 4795f5a..fd32979 100644
--- a/lib/diaspora_federation/validators/profile_validator.rb
+++ b/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
 
diff --git a/lib/diaspora_federation/validators/rules/birthday.rb b/lib/diaspora_federation/validators/rules/birthday.rb
index 89f97fe..682719c 100644
--- a/lib/diaspora_federation/validators/rules/birthday.rb
+++ b/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
diff --git a/lib/diaspora_federation/validators/rules/boolean.rb b/lib/diaspora_federation/validators/rules/boolean.rb
index ecc2b77..f2f4918 100644
--- a/lib/diaspora_federation/validators/rules/boolean.rb
+++ b/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
diff --git a/lib/diaspora_federation/validators/rules/diaspora_id.rb b/lib/diaspora_federation/validators/rules/diaspora_id.rb
index f17f7b7..591c621 100644
--- a/lib/diaspora_federation/validators/rules/diaspora_id.rb
+++ b/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
diff --git a/lib/diaspora_federation/validators/rules/guid.rb b/lib/diaspora_federation/validators/rules/guid.rb
index f559fc6..73077fa 100644
--- a/lib/diaspora_federation/validators/rules/guid.rb
+++ b/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
diff --git a/lib/diaspora_federation/validators/rules/not_nil.rb b/lib/diaspora_federation/validators/rules/not_nil.rb
index d3866ae..8d37d7e 100644
--- a/lib/diaspora_federation/validators/rules/not_nil.rb
+++ b/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
diff --git a/lib/diaspora_federation/validators/rules/public_key.rb b/lib/diaspora_federation/validators/rules/public_key.rb
index e7681ff..e2536e0 100644
--- a/lib/diaspora_federation/validators/rules/public_key.rb
+++ b/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
diff --git a/lib/diaspora_federation/validators/rules/tag_count.rb b/lib/diaspora_federation/validators/rules/tag_count.rb
index 9a74c15..6f100a8 100644
--- a/lib/diaspora_federation/validators/rules/tag_count.rb
+++ b/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