diff --git a/app/controllers/diaspora_federation/application_controller.rb b/app/controllers/diaspora_federation/application_controller.rb
index 586b503..820394f 100644
--- a/app/controllers/diaspora_federation/application_controller.rb
+++ b/app/controllers/diaspora_federation/application_controller.rb
@@ -1,5 +1,5 @@
 module DiasporaFederation
-  # Base-Controller for all DiasporaFederation-Controller
+  # Base controller for all DiasporaFederation controllers
   class ApplicationController < ActionController::Base
     before_action :set_locale
 
diff --git a/app/controllers/diaspora_federation/fetch_controller.rb b/app/controllers/diaspora_federation/fetch_controller.rb
index fddbb0b..13b682f 100644
--- a/app/controllers/diaspora_federation/fetch_controller.rb
+++ b/app/controllers/diaspora_federation/fetch_controller.rb
@@ -1,9 +1,9 @@
 require_dependency "diaspora_federation/application_controller"
 
 module DiasporaFederation
-  # this controller processes fetch requests
+  # This controller processes fetch requests.
   class FetchController < ApplicationController
-    # returns the fetched entity or a redirect
+    # Returns the fetched entity or a redirect
     #
     # GET /fetch/:type/:guid
     def fetch
diff --git a/app/controllers/diaspora_federation/h_card_controller.rb b/app/controllers/diaspora_federation/h_card_controller.rb
index 7f39a71..b30af8f 100644
--- a/app/controllers/diaspora_federation/h_card_controller.rb
+++ b/app/controllers/diaspora_federation/h_card_controller.rb
@@ -1,9 +1,9 @@
 require_dependency "diaspora_federation/application_controller"
 
 module DiasporaFederation
-  # this controller generates the hcard
+  # This controller generates the hcard.
   class HCardController < ApplicationController
-    # returns the hcard of the user
+    # Returns the hcard of the user
     #
     # GET /hcard/users/:guid
     def hcard
diff --git a/app/controllers/diaspora_federation/receive_controller.rb b/app/controllers/diaspora_federation/receive_controller.rb
index 2e86b07..1d9956f 100644
--- a/app/controllers/diaspora_federation/receive_controller.rb
+++ b/app/controllers/diaspora_federation/receive_controller.rb
@@ -1,11 +1,11 @@
 require_dependency "diaspora_federation/application_controller"
 
 module DiasporaFederation
-  # this controller processes receiving messages
+  # This controller processes receiving messages.
   class ReceiveController < ApplicationController
     before_action :check_for_xml
 
-    # receives public messages
+    # Receives public messages
     #
     # POST /receive/public
     def public
@@ -19,7 +19,7 @@ module DiasporaFederation
       render nothing: true, status: 202
     end
 
-    # receives private messages for a user
+    # Receives private messages for a user
     #
     # POST /receive/users/:guid
     def private
@@ -35,7 +35,7 @@ module DiasporaFederation
 
     private
 
-    # checks the xml parameter for legacy salmon slaps
+    # Checks the xml parameter for legacy salmon slaps
     # @deprecated
     def check_for_xml
       legacy_request = request.content_type.nil? || request.content_type == "application/x-www-form-urlencoded"
diff --git a/app/controllers/diaspora_federation/webfinger_controller.rb b/app/controllers/diaspora_federation/webfinger_controller.rb
index 850f6c2..0d1631f 100644
--- a/app/controllers/diaspora_federation/webfinger_controller.rb
+++ b/app/controllers/diaspora_federation/webfinger_controller.rb
@@ -1,9 +1,9 @@
 require_dependency "diaspora_federation/application_controller"
 
 module DiasporaFederation
-  # this controller handles all webfinger-specific requests
+  # This controller handles all webfinger-specific requests.
   class WebfingerController < ApplicationController
-    # returns the host-meta xml
+    # Returns the host-meta xml
     #
     # example:
     #   <?xml version="1.0" encoding="UTF-8"?>
@@ -16,7 +16,7 @@ module DiasporaFederation
       render xml: WebfingerController.host_meta_xml, content_type: "application/xrd+xml"
     end
 
-    # @deprecated this is the pre RFC 7033 webfinger
+    # @deprecated This is the pre RFC 7033 webfinger.
     #
     # example:
     #   <?xml version="1.0" encoding="UTF-8"?>
@@ -45,7 +45,7 @@ module DiasporaFederation
       end
     end
 
-    # creates the host-meta xml with the configured server_uri and caches it
+    # Creates the host-meta xml with the configured server_uri and caches it
     # @return [String] XML string
     def self.host_meta_xml
       @host_meta_xml ||= Discovery::HostMeta.from_base_url(DiasporaFederation.server_uri.to_s).to_xml
diff --git a/lib/diaspora_federation.rb b/lib/diaspora_federation.rb
index 2e05497..ea55dfd 100644
--- a/lib/diaspora_federation.rb
+++ b/lib/diaspora_federation.rb
@@ -48,7 +48,7 @@ module DiasporaFederation
     # @return [Callbacks] callbacks
     attr_reader :callbacks
 
-    # the pod url
+    # The pod url
     #
     # @overload server_uri
     #   @return [URI] the server uri
@@ -80,7 +80,7 @@ module DiasporaFederation
     #   @param [Integer] value max number of parallel requests
     attr_accessor :http_concurrency
 
-    # timeout in seconds for http-requests (default: +30+)
+    # Timeout in seconds for http-requests (default: +30+)
     #
     # @overload http_timeout
     #   @return [Integer] http timeout in seconds
@@ -98,15 +98,15 @@ module DiasporaFederation
     #   @param [Boolean] value verbose http output
     attr_accessor :http_verbose
 
-    # max redirects to follow
+    # Max redirects to follow
     # @return [Integer] max redirects
     attr_reader :http_redirect_limit
 
-    # user agent used for http-requests
+    # User agent used for http-requests
     # @return [String] user agent
     attr_reader :http_user_agent
 
-    # configure the federation library
+    # Configure the federation library
     #
     # @example
     #   DiasporaFederation.configure do |config|
@@ -120,7 +120,7 @@ module DiasporaFederation
       yield self
     end
 
-    # define the callbacks
+    # Define the callbacks
     #
     # In order to communicate with the application which uses the diaspora_federation gem
     # callbacks are introduced. The callbacks are used for getting required data from the
@@ -130,7 +130,7 @@ module DiasporaFederation
     #
     # fetch_person_for_webfinger
     #   Fetches person data from the application to form a WebFinger reply
-    #   @param [String] Diaspora ID of the person
+    #   @param [String] diaspora* ID of the person
     #   @return [DiasporaFederation::Discovery::WebFinger] person webfinger data
     #
     # fetch_person_for_hcard
@@ -144,13 +144,13 @@ module DiasporaFederation
     #   @param [DiasporaFederation::Entities::Person] person data
     #
     # fetch_private_key
-    #   Fetches a private key of a person by her Diaspora ID from the application
-    #   @param [String] Diaspora ID of the person
+    #   Fetches a private key of a person by her diaspora* ID from the application
+    #   @param [String] diaspora* ID of the person
     #   @return [OpenSSL::PKey::RSA] key
     #
     # fetch_public_key
-    #   Fetches a public key of a person by her Diaspora ID from the application
-    #   @param [String] Diaspora ID of the person
+    #   Fetches a public key of a person by her diaspora* ID from the application
+    #   @param [String] diaspora* ID of the person
     #   @return [OpenSSL::PKey::RSA] key
     #
     # fetch_related_entity
@@ -178,12 +178,12 @@ module DiasporaFederation
     #     see {Receiver.receive_private}
     #
     # fetch_public_entity
-    #   fetch a public entity from the database
+    #   Fetch a public entity from the database
     #   @param [String] entity_type (Post, StatusMessage, etc)
     #   @param [String] guid the guid of the entity
     #
     # fetch_person_url_to
-    #   fetch the url to path for a person
+    #   Fetch the url to path for a person
     #   @param [String] diaspora_id
     #   @param [String] path
     #
@@ -206,7 +206,7 @@ module DiasporaFederation
       @callbacks.instance_eval(&block)
     end
 
-    # validates if the engine is configured correctly
+    # Validates if the engine is configured correctly
     #
     # called from after_initialize
     # @raise [ConfigurationError] if the configuration is incomplete or invalid
diff --git a/lib/diaspora_federation/callbacks.rb b/lib/diaspora_federation/callbacks.rb
index 81f843b..fae3689 100644
--- a/lib/diaspora_federation/callbacks.rb
+++ b/lib/diaspora_federation/callbacks.rb
@@ -2,7 +2,7 @@ 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.
+    # Initializes a new Callbacks object with the event-keys that need to be defined
     #
     # @example
     #   Callbacks.new %i(
@@ -16,7 +16,7 @@ module DiasporaFederation
       @handlers = {}
     end
 
-    # defines a callback
+    # Defines a callback
     #
     # @example
     #   callbacks.on :some_event do |arg1|
@@ -33,7 +33,7 @@ module DiasporaFederation
       @handlers[event] = callback
     end
 
-    # triggers a callback
+    # Triggers a callback
     #
     # @example
     #   callbacks.trigger :some_event, "foo"
@@ -47,7 +47,7 @@ module DiasporaFederation
       @handlers[event].call(*args)
     end
 
-    # checks if all callbacks are defined
+    # Checks if all callbacks are defined
     # @return [Boolean]
     def definition_complete?
       missing_handlers.empty?
diff --git a/lib/diaspora_federation/discovery.rb b/lib/diaspora_federation/discovery.rb
index 95cd7e9..f4bd28d 100644
--- a/lib/diaspora_federation/discovery.rb
+++ b/lib/diaspora_federation/discovery.rb
@@ -1,7 +1,7 @@
 module DiasporaFederation
   # This module provides the namespace for the various classes implementing
   # WebFinger and other protocols used for metadata discovery on remote servers
-  # in the Diaspora* network.
+  # in the diaspora* network.
   module Discovery
   end
 end
diff --git a/lib/diaspora_federation/discovery/discovery.rb b/lib/diaspora_federation/discovery/discovery.rb
index c14c329..f141dca 100644
--- a/lib/diaspora_federation/discovery/discovery.rb
+++ b/lib/diaspora_federation/discovery/discovery.rb
@@ -1,19 +1,19 @@
 module DiasporaFederation
   module Discovery
-    # This class contains the logic to fetch all data for the given diaspora ID
+    # This class contains the logic to fetch all data for the given diaspora* ID.
     class Discovery
       include DiasporaFederation::Logging
 
-      # @return [String] the diaspora ID of the account
+      # @return [String] the diaspora* ID of the account
       attr_reader :diaspora_id
 
-      # create a discovery class for the diaspora-id
-      # @param [String] diaspora_id the diaspora id to discover
+      # Creates a discovery class for the diaspora* ID
+      # @param [String] diaspora_id the diaspora* ID to discover
       def initialize(diaspora_id)
         @diaspora_id = clean_diaspora_id(diaspora_id)
       end
 
-      # fetch all metadata for the account and saves it via callback
+      # Fetches all metadata for the account and saves it via callback
       # @return [Person]
       def fetch_and_save
         logger.info "Fetch data for #{diaspora_id}"
@@ -28,9 +28,9 @@ module DiasporaFederation
       private
 
       def validate_diaspora_id
-        # validates if the diaspora ID matches the diaspora ID in the webfinger response
+        # Validates if the diaspora* ID matches the diaspora* ID in the webfinger response
         return if diaspora_id == clean_diaspora_id(webfinger.acct_uri)
-        raise DiscoveryError, "Diaspora ID does not match: Wanted #{diaspora_id} but got" \
+        raise DiscoveryError, "diaspora* ID does not match: Wanted #{diaspora_id} but got" \
                               " #{clean_diaspora_id(webfinger.acct_uri)}"
       end
 
@@ -59,7 +59,7 @@ module DiasporaFederation
       end
 
       def legacy_webfinger_url_from_host_meta
-        # this tries the xrd url with https first, then falls back to http
+        # This tries the xrd url with https first, then falls back to http.
         host_meta = HostMeta.from_xml get(host_meta_url, true)
         host_meta.webfinger_template_url.gsub("{uri}", "acct:#{diaspora_id}")
       end
diff --git a/lib/diaspora_federation/discovery/h_card.rb b/lib/diaspora_federation/discovery/h_card.rb
index 242d5bf..049a656 100644
--- a/lib/diaspora_federation/discovery/h_card.rb
+++ b/lib/diaspora_federation/discovery/h_card.rb
@@ -1,6 +1,6 @@
 module DiasporaFederation
   module Discovery
-    # This class provides the means of generating an parsing account data to and
+    # This class provides the means of generating and parsing account data to and
     # from the hCard format.
     # hCard is based on +RFC 2426+ (vCard) which got superseded by +RFC 6350+.
     # There is a draft for a new h-card format specification, that makes use of
@@ -46,7 +46,7 @@ module DiasporaFederation
       property :guid
 
       # @!attribute [r] nickname
-      #   the first part of the diaspora ID
+      #   The first part of the diaspora* ID
       #   @return [String] nickname
       property :nickname
 
@@ -56,7 +56,7 @@ module DiasporaFederation
 
       # @!attribute [r] url
       #   @deprecated should be changed to the profile url. The pod url is in
-      #     the WebFinger (see {WebFinger#seed_url}, will affect older Diaspora*
+      #     the WebFinger (see {WebFinger#seed_url}, will affect older diaspora*
       #     installations).
       #
       #   @return [String] link to the pod
@@ -83,7 +83,7 @@ module DiasporaFederation
 
       # @!attribute [r] first_name
       #   @deprecated We decided to only use one name field, these should be removed
-      #     in later iterations (will affect older Diaspora* installations).
+      #     in later iterations (will affect older diaspora* installations).
       #
       #   @see #full_name
       #   @return [String] first name
@@ -91,7 +91,7 @@ module DiasporaFederation
 
       # @!attribute [r] last_name
       #   @deprecated We decided to only use one name field, these should be removed
-      #     in later iterations (will affect older Diaspora* installations).
+      #     in later iterations (will affect older diaspora* installations).
       #
       #   @see #full_name
       #   @return [String] last name
@@ -100,7 +100,7 @@ module DiasporaFederation
       # @!attribute [r] searchable
       #   @deprecated As this is a simple property, consider move to WebFinger instead
       #     of HCard. vCard has no comparable field for this information, but
-      #     Webfinger may declare arbitrary properties (will affect older Diaspora*
+      #     Webfinger may declare arbitrary properties (will affect older diaspora*
       #     installations).
       #
       #   flag if a user is searchable by name
@@ -152,7 +152,7 @@ module DiasporaFederation
         builder.doc.to_xhtml(indent: 2, indent_text: " ")
       end
 
-      # Creates a new HCard instance from the given HTML string.
+      # Creates a new HCard instance from the given HTML string
       # @param html_string [String] HTML string
       # @return [HCard] HCard instance
       # @raise [InvalidData] if the HTML string is invalid or incomplete
@@ -219,7 +219,7 @@ module DiasporaFederation
         end
       end
 
-      # Calls {HCard#add_property} for a simple text property.
+      # Calls {HCard#add_property} for a simple text property
       # @param container [Nokogiri::XML::Element] parent element
       # @param name [Symbol] property name
       # @param class_name [String] HTML class name
diff --git a/lib/diaspora_federation/discovery/host_meta.rb b/lib/diaspora_federation/discovery/host_meta.rb
index 15887f6..2d71a63 100644
--- a/lib/diaspora_federation/discovery/host_meta.rb
+++ b/lib/diaspora_federation/discovery/host_meta.rb
@@ -4,7 +4,7 @@ module DiasporaFederation
     # Generates and parses Host Meta documents.
     #
     # This is a minimal implementation of the standard, only to the degree of what
-    # is used for the purposes of the Diaspora* protocol. (e.g. WebFinger)
+    # is used for the purposes of the diaspora* protocol. (e.g. WebFinger)
     #
     # @example Creating a Host Meta document
     #   doc = HostMeta.from_base_url("https://pod.example.tld/")
@@ -19,7 +19,7 @@ module DiasporaFederation
     class HostMeta
       private_class_method :new
 
-      # create a new host-meta instance
+      # Creates a new host-meta instance
       # @param [String] webfinger_url the webfinger-url
       def initialize(webfinger_url)
         @webfinger_url = webfinger_url
diff --git a/lib/diaspora_federation/discovery/web_finger.rb b/lib/diaspora_federation/discovery/web_finger.rb
index 4ce0cdd..4d2da11 100644
--- a/lib/diaspora_federation/discovery/web_finger.rb
+++ b/lib/diaspora_federation/discovery/web_finger.rb
@@ -1,9 +1,7 @@
 module DiasporaFederation
   module Discovery
-    # The WebFinger document used for Diaspora* user discovery is based on an older
-    # draft of the specification you can find in the wiki of the "webfinger" project
-    # on {http://code.google.com/p/webfinger/wiki/WebFingerProtocol Google Code}
-    # (from around 2010).
+    # The WebFinger document used for diaspora* user discovery is based on an
+    # {http://tools.ietf.org/html/draft-jones-appsawg-webfinger older draft of the specification}.
     #
     # In the meantime an actual RFC draft has been in development, which should
     # serve as a base for all future changes of this implementation.
@@ -30,7 +28,6 @@ module DiasporaFederation
     #
     # @see http://tools.ietf.org/html/draft-jones-appsawg-webfinger "WebFinger" -
     #   current draft
-    # @see http://code.google.com/p/webfinger/wiki/CommonLinkRelations
     # @see http://www.iana.org/assignments/link-relations/link-relations.xhtml
     #   official list of IANA link relations
     class WebFinger < Entity
@@ -58,7 +55,7 @@ module DiasporaFederation
       property :profile_url
 
       # @!attribute [r] atom_url
-      #   This atom feed is an Activity Stream of the user's public posts. Diaspora
+      #   This atom feed is an Activity Stream of the user's public posts. diaspora*
       #   pods SHOULD publish an Activity Stream of public posts, but there is
       #   currently no requirement to be able to read Activity Streams.
       #   @see http://activitystrea.ms/ Activity Streams specification
@@ -82,7 +79,7 @@ module DiasporaFederation
       # @!attribute [r] guid
       #   @deprecated Either convert these to +Property+ elements or move to the
       #     +hCard+, which actually has fields for an +UID+ defined in the +vCard+
-      #     specification (will affect older Diaspora* installations).
+      #     specification (will affect older diaspora* installations).
       #
       #   @see HCard#guid
       #   @see Entities::Person#guid
@@ -92,7 +89,7 @@ module DiasporaFederation
       # @!attribute [r] public_key
       #   @deprecated Either convert these to +Property+ elements or move to the
       #     +hCard+, which actually has fields for an +KEY+ defined in the +vCard+
-      #     specification (will affect older Diaspora* installations).
+      #     specification (will affect older diaspora* installations).
       #
       #   @see HCard#public_key
       #
@@ -111,7 +108,7 @@ module DiasporaFederation
 
       # @deprecated This should be a +Property+ or moved to the +hCard+, but +Link+
       #   is inappropriate according to the specification (will affect older
-      #   Diaspora* installations).
+      #   diaspora* installations).
       # +guid+ link relation
       REL_GUID = "http://joindiaspora.com/guid".freeze
 
@@ -130,11 +127,11 @@ module DiasporaFederation
 
       # @deprecated This should be a +Property+ or moved to the +hcard+, but +Link+
       #   is inappropriate according to the specification (will affect older
-      #   Diaspora* installations).
+      #   diaspora* installations).
       # +pubkey+ link relation
       REL_PUBKEY = "diaspora-public-key".freeze
 
-      # Create the XML string from the current WebFinger instance
+      # Creates the XML string from the current WebFinger instance
       # @return [String] XML string
       def to_xml
         doc = XrdDocument.new
@@ -146,7 +143,7 @@ module DiasporaFederation
         doc.to_xml
       end
 
-      # Create a WebFinger instance from the given XML string.
+      # Creates a WebFinger instance from the given XML string
       # @param [String] webfinger_xml WebFinger XML string
       # @return [WebFinger] WebFinger instance
       # @raise [InvalidData] if the given XML string is invalid or incomplete
@@ -229,7 +226,7 @@ module DiasporaFederation
         element ? element[:template] : nil
       end
 
-      # this method is used to parse the alias_url from the XML.
+      # This method is used to parse the alias_url from the XML.
       # * redmatrix has sometimes no alias, return nil
       # * old pods had quotes around the alias url, this can be removed later
       # * friendica has two aliases and the first is with "acct:": return only an URL starting with http (or https)
diff --git a/lib/diaspora_federation/discovery/xrd_document.rb b/lib/diaspora_federation/discovery/xrd_document.rb
index f0a3528..55c1b4f 100644
--- a/lib/diaspora_federation/discovery/xrd_document.rb
+++ b/lib/diaspora_federation/discovery/xrd_document.rb
@@ -1,7 +1,7 @@
 module DiasporaFederation
   module Discovery
     # This class implements basic handling of XRD documents as far as it is
-    # necessary in the context of the protocols used with Diaspora* federation.
+    # necessary in the context of the protocols used with diaspora* federation.
     #
     # @note {http://tools.ietf.org/html/rfc6415 RFC 6415} recommends that servers
     #   should also offer the JRD format in addition to the XRD representation.
diff --git a/lib/diaspora_federation/entities.rb b/lib/diaspora_federation/entities.rb
index dee3313..343e502 100644
--- a/lib/diaspora_federation/entities.rb
+++ b/lib/diaspora_federation/entities.rb
@@ -1,8 +1,8 @@
 module DiasporaFederation
   # This namespace contains all the entities used to encapsulate data that is
-  # passed around in the Diaspora* network as part of the federation protocol.
+  # passed around in the diaspora* network as part of the federation protocol.
   #
-  # All entities must be defined in this namespace. otherwise the XML
+  # All entities must be defined in this namespace. Otherwise the XML
   # de-serialization will fail.
   module Entities
   end
diff --git a/lib/diaspora_federation/entities/account_deletion.rb b/lib/diaspora_federation/entities/account_deletion.rb
index 2dff80f..7c4553c 100644
--- a/lib/diaspora_federation/entities/account_deletion.rb
+++ b/lib/diaspora_federation/entities/account_deletion.rb
@@ -1,17 +1,17 @@
 module DiasporaFederation
   module Entities
-    # this entity is sent when account was deleted on a remote pod
+    # This entity is sent when an account was deleted on a remote pod.
     #
     # @see Validators::AccountDeletionValidator
     class AccountDeletion < Entity
       # @!attribute [r] author
-      #   The diaspora ID of the deleted account
+      #   The diaspora* ID of the deleted account
       #   @see Person#author
-      #   @return [String] diaspora ID
+      #   @return [String] diaspora* ID
       # @!attribute [r] diaspora_id
       #   Alias for author
       #   @see AccountDeletion#author
-      #   @return [String] diaspora ID
+      #   @return [String] diaspora* ID
       property :author, alias: :diaspora_id, xml_name: :diaspora_handle
 
       # @return [String] string representation of this object
diff --git a/lib/diaspora_federation/entities/comment.rb b/lib/diaspora_federation/entities/comment.rb
index 0c40dfc..561938b 100644
--- a/lib/diaspora_federation/entities/comment.rb
+++ b/lib/diaspora_federation/entities/comment.rb
@@ -1,10 +1,10 @@
 module DiasporaFederation
   module Entities
-    # this entity represents a comment to some kind of post (e.g. status message)
+    # This entity represents a comment to some kind of post (e.g. status message).
     #
     # @see Validators::CommentValidator
     class Comment < Entity
-      # old signature order
+      # Old signature order
       # @deprecated
       LEGACY_SIGNATURE_ORDER = %i(guid parent_guid text author).freeze
 
@@ -18,7 +18,7 @@ module DiasporaFederation
       property :text
 
       # @!attribute [r] created_at
-      #   comment entity creation time
+      #   Comment entity creation time
       #   @return [Time] creation time
       property :created_at, default: -> { Time.now.utc }
     end
diff --git a/lib/diaspora_federation/entities/contact.rb b/lib/diaspora_federation/entities/contact.rb
index b7390c9..02451f9 100644
--- a/lib/diaspora_federation/entities/contact.rb
+++ b/lib/diaspora_federation/entities/contact.rb
@@ -1,18 +1,18 @@
 module DiasporaFederation
   module Entities
-    # this entity represents a contact with another person. A user issues it
-    # when he starts sharing/following with another user.
+    # This entity represents a contact with another person. A user issues it
+    # when they start sharing/following with another user.
     #
     # @see Validators::ContactValidator
     class Contact < Entity
       # @!attribute [r] author
-      #   The diaspora ID of the person who shares his profile
+      #   The diaspora* ID of the person who shares their profile
       #   @see Person#author
       #   @return [String] sender ID
       property :author
 
       # @!attribute [r] recipient
-      #   The diaspora ID of the person who will be shared with
+      #   The diaspora* ID of the person who will be shared with
       #   @see Validation::Rule::DiasporaId
       #   @return [String] recipient ID
       property :recipient
diff --git a/lib/diaspora_federation/entities/conversation.rb b/lib/diaspora_federation/entities/conversation.rb
index 8801a44..9745ffb 100644
--- a/lib/diaspora_federation/entities/conversation.rb
+++ b/lib/diaspora_federation/entities/conversation.rb
@@ -1,11 +1,11 @@
 module DiasporaFederation
   module Entities
-    # this entity represents a private conversation between users
+    # This entity represents a private conversation between users.
     #
     # @see Validators::ConversationValidator
     class Conversation < Entity
       # @!attribute [r] guid
-      #   a random string of at least 16 chars.
+      #   A random string of at least 16 chars
       #   @see Validation::Rule::Guid
       #   @return [String] conversation guid
       property :guid
@@ -23,14 +23,14 @@ module DiasporaFederation
       entity :messages, [Entities::Message], default: []
 
       # @!attribute [r] author
-      #   The diaspora ID of the person initiated the conversation.
+      #   The diaspora* ID of the person initiated the conversation
       #   @see Person#author
-      #   @return [String] diaspora ID
+      #   @return [String] diaspora* ID
       property :author, xml_name: :diaspora_handle
 
       # @!attribute [r] participants
-      #   The diaspora IDs of the persons participating the conversation separated by ";".
-      #   @return [String] participants diaspora IDs
+      #   The diaspora* IDs of the persons participating the conversation separated by ";"
+      #   @return [String] participants diaspora* IDs
       property :participants, xml_name: :participant_handles
 
       private
diff --git a/lib/diaspora_federation/entities/like.rb b/lib/diaspora_federation/entities/like.rb
index e932997..ea182fb 100644
--- a/lib/diaspora_federation/entities/like.rb
+++ b/lib/diaspora_federation/entities/like.rb
@@ -1,10 +1,10 @@
 module DiasporaFederation
   module Entities
-    # this entity represents a like to some kind of post (e.g. status message)
+    # This entity represents a like to some kind of post (e.g. status message).
     #
     # @see Validators::LikeValidator
     class Like < Entity
-      # old signature order
+      # Old signature order
       # @deprecated
       LEGACY_SIGNATURE_ORDER = %i(positive guid parent_type parent_guid author).freeze
 
@@ -12,14 +12,14 @@ module DiasporaFederation
 
       # @!attribute [r] positive
       #   If +true+ set a like, if +false+, set a dislike (dislikes are currently not
-      #   implemented in the Diaspora frontend).
+      #   implemented in the diaspora* frontend).
       #   @return [Boolean] is it a like or a dislike
       property :positive
 
       # @!attribute [r] parent_type
-      #   A string describing the type of the parent.
+      #   A string describing the type of the parent
       #   Can be "Post" or "Comment" (Comments are currently not implemented in the
-      #   Diaspora Frontend).
+      #   diaspora* frontend).
       #   @return [String] parent type
       property :parent_type, xml_name: :target_type
     end
diff --git a/lib/diaspora_federation/entities/location.rb b/lib/diaspora_federation/entities/location.rb
index e1ce433..25aaf84 100644
--- a/lib/diaspora_federation/entities/location.rb
+++ b/lib/diaspora_federation/entities/location.rb
@@ -1,6 +1,6 @@
 module DiasporaFederation
   module Entities
-    # this entity is used to specify a location data and used embedded in a status message
+    # This entity is used to specify location data and used embedded in a status message.
     #
     # @see Validators::LocationValidator
     class Location < Entity
diff --git a/lib/diaspora_federation/entities/message.rb b/lib/diaspora_federation/entities/message.rb
index 9d0f1f6..281f200 100644
--- a/lib/diaspora_federation/entities/message.rb
+++ b/lib/diaspora_federation/entities/message.rb
@@ -1,27 +1,27 @@
 module DiasporaFederation
   module Entities
-    # this entity represents a private message exchanged in private conversation
+    # This entity represents a private message exchanged in private conversation.
     #
     # @see Validators::MessageValidator
     class Message < Entity
-      # old signature order
+      # Old signature order
       # @deprecated
       LEGACY_SIGNATURE_ORDER = %i(guid parent_guid text created_at author conversation_guid).freeze
 
       include Relayable
 
       # @!attribute [r] text
-      #   text of the message composed by a user
+      #   Text of the message composed by a user
       #   @return [String] text
       property :text
 
       # @!attribute [r] created_at
-      #   message creation time
+      #   Message creation time
       #   @return [Time] creation time
       property :created_at, default: -> { Time.now.utc }
 
       # @!attribute [r] conversation_guid
-      #   guid of a conversation this message belongs to
+      #   Guid of a conversation this message belongs to
       #   @see Conversation#guid
       #   @return [String] conversation guid
       property :conversation_guid
diff --git a/lib/diaspora_federation/entities/participation.rb b/lib/diaspora_federation/entities/participation.rb
index 4eb4808..63fdaae 100644
--- a/lib/diaspora_federation/entities/participation.rb
+++ b/lib/diaspora_federation/entities/participation.rb
@@ -1,28 +1,28 @@
 module DiasporaFederation
   module Entities
-    # participation is sent to subscribe a user on updates for some post
+    # Participation is sent to subscribe a user on updates for some post.
     #
     # @see Validators::Participation
     class Participation < Entity
-      # old signature order
+      # Old signature order
       # @deprecated
       LEGACY_SIGNATURE_ORDER = %i(guid parent_type parent_guid author).freeze
 
       include Relayable
 
       # @!attribute [r] parent_type
-      #   a string describing a type of the target to subscribe on.
-      #   currently only "Post" is supported.
+      #   A string describing a type of the target to subscribe on
+      #   Currently only "Post" is supported.
       #   @return [String] parent type
       property :parent_type, xml_name: :target_type
 
-      # It is only valid to receive a {Participation} from the author itself.
+      # It is only valid to receive a {Participation} from the author themself.
       # @deprecated remove after {Participation} doesn't include {Relayable} anymore
       def sender_valid?(sender)
         sender == author
       end
 
-      # validates that the parent exists and the parent author is local
+      # Validates that the parent exists and the parent author is local
       def validate_parent
         parent = DiasporaFederation.callbacks.trigger(:fetch_related_entity, parent_type, parent_guid)
         raise ParentNotLocal, "obj=#{self}" unless parent && parent.local
diff --git a/lib/diaspora_federation/entities/person.rb b/lib/diaspora_federation/entities/person.rb
index 3844fb0..44868d7 100644
--- a/lib/diaspora_federation/entities/person.rb
+++ b/lib/diaspora_federation/entities/person.rb
@@ -1,6 +1,6 @@
 module DiasporaFederation
   module Entities
-    # this entity contains the base data of a person
+    # This entity contains the base data of a person.
     #
     # @see Validators::PersonValidator
     class Person < Entity
@@ -12,13 +12,13 @@ module DiasporaFederation
       property :guid
 
       # @!attribute [r] author
-      #   The diaspora ID of the person
+      #   The diaspora* ID of the person
       #   @see Validation::Rule::DiasporaId
-      #   @return [String] diaspora ID
+      #   @return [String] diaspora* ID
       # @!attribute [r] diaspora_id
-      #   Alias for author
+      #   alias for author
       #   @see Person#author
-      #   @return [String] diaspora ID
+      #   @return [String] diaspora* ID
       property :author, alias: :diaspora_id, xml_name: :diaspora_handle
 
       # @!attribute [r] url
@@ -27,7 +27,7 @@ module DiasporaFederation
       property :url
 
       # @!attribute [r] profile
-      #   all profile data of the person
+      #   All profile data of the person
       #   @return [Profile] the profile of the person
       entity :profile, Entities::Profile
 
diff --git a/lib/diaspora_federation/entities/photo.rb b/lib/diaspora_federation/entities/photo.rb
index cf575f0..23066fb 100644
--- a/lib/diaspora_federation/entities/photo.rb
+++ b/lib/diaspora_federation/entities/photo.rb
@@ -1,19 +1,19 @@
 module DiasporaFederation
   module Entities
-    # this entity represents photo and it is federated as a part of a status message
+    # This entity represents a photo and it is federated as a part of a status message.
     #
     # @see Validators::PhotoValidator
     class Photo < Entity
       # @!attribute [r] guid
-      #   a random string of at least 16 chars.
+      #   A random string of at least 16 chars
       #   @see Validation::Rule::Guid
       #   @return [String] guid
       property :guid
 
       # @!attribute [r] author
-      #   The diaspora ID of the person who uploaded the photo
+      #   The diaspora* ID of the person who uploaded the photo
       #   @see Person#author
-      #   @return [String] author diaspora ID
+      #   @return [String] author diaspora* ID
       property :author, xml_name: :diaspora_handle
 
       # @!attribute [r] public
@@ -22,12 +22,12 @@ module DiasporaFederation
       property :public, default: false
 
       # @!attribute [r] created_at
-      #   photo entity creation time
+      #   Photo entity creation time
       #   @return [Time] creation time
       property :created_at, default: -> { Time.now.utc }
 
       # @!attribute [r] remote_photo_path
-      #   an url of the photo on a remote server
+      #   An url of the photo on a remote server
       #   @return [String] remote photo url
       property :remote_photo_path
 
@@ -40,18 +40,18 @@ module DiasporaFederation
       property :text, default: nil
 
       # @!attribute [r] status_message_guid
-      #   guid of a status message this message belongs to
+      #   Guid of a status message this message belongs to
       #   @see StatusMessage#guid
       #   @return [String] guid
       property :status_message_guid
 
       # @!attribute [r] height
-      #   photo height
+      #   Photo height
       #   @return [String] height
       property :height
 
       # @!attribute [r] width
-      #   photo width
+      #   Photo width
       #   @return [String] width
       property :width
     end
diff --git a/lib/diaspora_federation/entities/poll.rb b/lib/diaspora_federation/entities/poll.rb
index 901a657..4eeb916 100644
--- a/lib/diaspora_federation/entities/poll.rb
+++ b/lib/diaspora_federation/entities/poll.rb
@@ -1,11 +1,11 @@
 module DiasporaFederation
   module Entities
-    # this entity represents a poll ant it is federated as an optional part of a status message
+    # This entity represents a poll and it is federated as an optional part of a status message.
     #
     # @see Validators::PollValidator
     class Poll < Entity
       # @!attribute [r] guid
-      #   a random string of at least 16 chars.
+      #   A random string of at least 16 chars
       #   @see Validation::Rule::Guid
       #   @return [String] poll guid
       property :guid
@@ -16,7 +16,7 @@ module DiasporaFederation
       property :question
 
       # @!attribute [r] poll_answers
-      #   array of possible answer to the poll
+      #   Array of possible answers for the poll
       #   @return [[Entities::PollAnswer]] poll answers
       entity :poll_answers, [Entities::PollAnswer]
     end
diff --git a/lib/diaspora_federation/entities/poll_answer.rb b/lib/diaspora_federation/entities/poll_answer.rb
index d1c5b17..85ab83f 100644
--- a/lib/diaspora_federation/entities/poll_answer.rb
+++ b/lib/diaspora_federation/entities/poll_answer.rb
@@ -1,11 +1,11 @@
 module DiasporaFederation
   module Entities
-    # this entity represents a poll answer and is federated as a part of the Poll entity
+    # This entity represents a poll answer and is federated as a part of the Poll entity.
     #
     # @see Validators::PollAnswerValidator
     class PollAnswer < Entity
       # @!attribute [r] guid
-      #   a random string of at least 16 chars.
+      #   A random string of at least 16 chars
       #   @see Validation::Rule::Guid
       #   @return [String] guid
       property :guid
diff --git a/lib/diaspora_federation/entities/poll_participation.rb b/lib/diaspora_federation/entities/poll_participation.rb
index 3d6d5fc..24418a1 100644
--- a/lib/diaspora_federation/entities/poll_participation.rb
+++ b/lib/diaspora_federation/entities/poll_participation.rb
@@ -1,10 +1,10 @@
 module DiasporaFederation
   module Entities
-    # this entity represents a participation in poll, i.e. it is issued when a user votes for an answer in a poll
+    # This entity represents a participation in poll, i.e. it is issued when a user votes for an answer in a poll.
     #
     # @see Validators::PollParticipationValidator
     class PollParticipation < Entity
-      # old signature order
+      # Old signature order
       # @deprecated
       LEGACY_SIGNATURE_ORDER = %i(guid parent_guid author poll_answer_guid).freeze
 
@@ -14,7 +14,7 @@ module DiasporaFederation
       include Relayable
 
       # @!attribute [r] poll_answer_guid
-      #   guid of the answer selected by the user.
+      #   Guid of the answer selected by the user
       #   @see PollAnswer#guid
       #   @return [String] poll answer guid
       property :poll_answer_guid
diff --git a/lib/diaspora_federation/entities/post.rb b/lib/diaspora_federation/entities/post.rb
index e595472..5ef961c 100644
--- a/lib/diaspora_federation/entities/post.rb
+++ b/lib/diaspora_federation/entities/post.rb
@@ -1,26 +1,26 @@
 module DiasporaFederation
   module Entities
-    # this is a module that defines common properties for a post which
+    # This is a module that defines common properties for a post which
     # include {StatusMessage} and {Reshare}.
     module Post
-      # on inclusion of this module the required properties for a post are added to the object that includes it
+      # On inclusion of this module the required properties for a post are added to the object that includes it.
       #
       # @!attribute [r] author
-      #   The diaspora ID of the person who posts the post
+      #   The diaspora* ID of the person who posts the post
       #   @see Person#author
-      #   @return [String] diaspora ID
+      #   @return [String] diaspora* ID
       #
       # @!attribute [r] guid
-      #   a random string of at least 16 chars.
+      #   A random string of at least 16 chars
       #   @see Validation::Rule::Guid
       #   @return [String] status message guid
       #
       # @!attribute [r] created_at
-      #   post entity creation time
+      #   Post entity creation time
       #   @return [Time] creation time
       #
       # @!attribute [r] provider_display_name
-      #   a string that describes a means by which a user has posted the post
+      #   A string that describes a means by which a user has posted the post
       #   @return [String] provider display name
       #
       # @param [Entity] entity the entity in which it is included
diff --git a/lib/diaspora_federation/entities/profile.rb b/lib/diaspora_federation/entities/profile.rb
index e7f3bfb..a61bbde 100644
--- a/lib/diaspora_federation/entities/profile.rb
+++ b/lib/diaspora_federation/entities/profile.rb
@@ -1,22 +1,22 @@
 module DiasporaFederation
   module Entities
-    # this entity contains all the profile data of a person
+    # This entity contains all the profile data of a person.
     #
     # @see Validators::ProfileValidator
     class Profile < Entity
       # @!attribute [r] author
-      #   The diaspora ID of the person
+      #   The diaspora* ID of the person
       #   @see Person#author
-      #   @return [String] diaspora ID
+      #   @return [String] diaspora* ID
       # @!attribute [r] diaspora_id
       #   Alias for author
       #   @see Profile#author
-      #   @return [String] diaspora ID
+      #   @return [String] diaspora* ID
       property :author, alias: :diaspora_id, xml_name: :diaspora_handle
 
       # @!attribute [r] first_name
       #   @deprecated We decided to only use one name field, these should be removed
-      #     in later iterations (will affect older Diaspora* installations).
+      #     in later iterations (will affect older diaspora* installations).
       #   @see #full_name
       #   @see Discovery::HCard#first_name
       #   @return [String] first name
@@ -24,7 +24,7 @@ module DiasporaFederation
 
       # @!attribute [r] last_name
       #   @deprecated We decided to only use one name field, these should be removed
-      #     in later iterations (will affect older Diaspora* installations).
+      #     in later iterations (will affect older diaspora* installations).
       #   @see #full_name
       #   @see Discovery::HCard#last_name
       #   @return [String] last name
diff --git a/lib/diaspora_federation/entities/related_entity.rb b/lib/diaspora_federation/entities/related_entity.rb
index 9acf788..6f8cf9f 100644
--- a/lib/diaspora_federation/entities/related_entity.rb
+++ b/lib/diaspora_federation/entities/related_entity.rb
@@ -4,9 +4,9 @@ module DiasporaFederation
     # another entity).
     class RelatedEntity < Entity
       # @!attribute [r] author
-      #   The diaspora ID of the author.
+      #   The diaspora* ID of the author
       #   @see Person#author
-      #   @return [String] diaspora ID
+      #   @return [String] diaspora* ID
       property :author
 
       # @!attribute [r] local
@@ -15,12 +15,12 @@ module DiasporaFederation
       property :local
 
       # @!attribute [r] public
-      #   shows whether the entity is visible to everyone or only to some aspects
+      #   Shows whether the entity is visible to everyone or only to some aspects
       #   @return [Boolean] is it public
       property :public, default: false
 
       # @!attribute [r] parent
-      #   if the entity also have a parent (Comment or Like), +nil+ if it has no parent
+      #   Parent if the entity also has a parent (Comment or Like) or +nil+ if it has no parent
       #   @return [RelatedEntity] parent entity
       entity :parent, Entities::RelatedEntity, default: nil
 
diff --git a/lib/diaspora_federation/entities/relayable.rb b/lib/diaspora_federation/entities/relayable.rb
index 86f50d2..c323213 100644
--- a/lib/diaspora_federation/entities/relayable.rb
+++ b/lib/diaspora_federation/entities/relayable.rb
@@ -1,32 +1,32 @@
 module DiasporaFederation
   module Entities
-    # this is a module that defines common properties for relayable entities
+    # This is a module that defines common properties for relayable entities
     # which include Like, Comment, Participation, Message, etc. Each relayable
-    # has a parent, identified by guid. Relayables also are signed and signing/verification
+    # has a parent, identified by guid. Relayables are also signed and signing/verification
     # logic is embedded into Salmon XML processing code.
     module Relayable
       include Logging
 
-      # digest instance used for signing
+      # Digest instance used for signing
       DIGEST = OpenSSL::Digest::SHA256.new
 
-      # order from the parsed xml for signature
+      # Order from the parsed xml for signature
       # @return [Array] order from xml
       attr_reader :xml_order
 
-      # additional properties from parsed xml
+      # Additional properties from parsed xml
       # @return [Hash] additional xml elements
       attr_reader :additional_xml_elements
 
-      # on inclusion of this module the required properties for a relayable are added to the object that includes it
+      # On inclusion of this module the required properties for a relayable are added to the object that includes it.
       #
       # @!attribute [r] author
-      #   The diaspora ID of the author.
+      #   The diaspora* ID of the author
       #   @see Person#author
-      #   @return [String] diaspora ID
+      #   @return [String] diaspora* ID
       #
       # @!attribute [r] guid
-      #   a random string of at least 16 chars.
+      #   A random string of at least 16 chars
       #   @see Validation::Rule::Guid
       #   @return [String] comment guid
       #
@@ -35,20 +35,20 @@ module DiasporaFederation
       #   @return [String] parent guid
       #
       # @!attribute [r] author_signature
-      #   Contains a signature of the entity using the private key of the author of a post itself.
+      #   Contains a signature of the entity using the private key of the author of a post itself
       #   The presence of this signature is mandatory. Without it the entity won't be accepted by
       #   a target pod.
       #   @return [String] author signature
       #
       # @!attribute [r] parent_author_signature
       #   Contains a signature of the entity using the private key of the author of a parent post
-      #   This signature is required only when federation from upstream (parent) post author to
+      #   This signature is required only when federating from upstream (parent) post author to
       #   downstream subscribers. This is the case when the parent author has to resend a relayable
-      #   received from one of his subscribers to all others.
+      #   received from one of their subscribers to all others.
       #   @return [String] parent author signature
       #
       # @!attribute [r] parent
-      #   meta information about the parent object
+      #   Meta information about the parent object
       #   @return [RelatedEntity] parent entity
       #
       # @param [Entity] klass the entity in which it is included
@@ -78,12 +78,12 @@ module DiasporaFederation
         super(data)
       end
 
-      # verifies the signatures (+author_signature+ and +parent_author_signature+ if needed)
+      # Verifies the signatures (+author_signature+ and +parent_author_signature+ if needed).
       # @raise [SignatureVerificationFailed] if the signature is not valid or no public key is found
       def verify_signatures
         verify_signature(author, :author_signature)
 
-        # this happens only on downstream federation
+        # This happens only on downstream federation.
         verify_signature(parent.author, :parent_author_signature) unless parent.local
       end
 
@@ -116,7 +116,7 @@ module DiasporaFederation
         logger.info "event=verify_signature signature=#{signature_key} status=valid obj=#{self}"
       end
 
-      # sign with author key
+      # Sign with author key
       # @raise [AuthorPrivateKeyNotFound] if the author private key is not found
       # @return [String] A Base64 encoded signature of #signature_data with key
       def sign_with_author
@@ -127,7 +127,7 @@ module DiasporaFederation
         end
       end
 
-      # sign with parent author key, if the parent author is local (if the private key is found)
+      # Sign with parent author key, if the parent author is local (if the private key is found)
       # @return [String] A Base64 encoded signature of #signature_data with key
       def sign_with_parent_author_if_available
         privkey = DiasporaFederation.callbacks.trigger(:fetch_private_key, parent.author)
@@ -159,7 +159,7 @@ module DiasporaFederation
         end
       end
 
-      # the order for signing
+      # The order for signing
       # @return [Array]
       def signature_order
         xml_order.nil? ? self.class::LEGACY_SIGNATURE_ORDER : xml_order.reject {|name| name =~ /signature/ }
@@ -171,7 +171,7 @@ module DiasporaFederation
         signature_order.map {|name| data[name] }.join(";")
       end
 
-      # override class methods from {Entity} to parse the xml
+      # Override class methods from {Entity} to parse the xml
       module ParseXML
         private
 
@@ -181,7 +181,7 @@ module DiasporaFederation
           # Use all known properties to build the Entity (entity_data). All additional xml elements
           # are respected and attached to a hash as string (additional_xml_elements). It also remembers
           # the order of the xml-nodes (xml_order). This is needed to support receiving objects from
-          # the future versions of Diaspora, where new elements may have been added.
+          # the future versions of diaspora*, where new elements may have been added.
           entity_data = {}
           additional_xml_elements = {}
 
@@ -209,14 +209,14 @@ module DiasporaFederation
           data[:parent] = DiasporaFederation.callbacks.trigger(:fetch_related_entity, type, guid)
 
           unless data[:parent]
-            # fetch and receive parent from remote, if not available locally
+            # Fetch and receive parent from remote, if not available locally
             Federation::Fetcher.fetch_public(data[:author], type, guid)
             data[:parent] = DiasporaFederation.callbacks.trigger(:fetch_related_entity, type, guid)
           end
         end
       end
 
-      # Raised, if creating the author_signature failes, because the private key was not found
+      # Raised, if creating the author_signature fails, because the private key was not found
       class AuthorPrivateKeyNotFound < RuntimeError
       end
 
diff --git a/lib/diaspora_federation/entities/relayable_retraction.rb b/lib/diaspora_federation/entities/relayable_retraction.rb
index d1ded88..48063ab 100644
--- a/lib/diaspora_federation/entities/relayable_retraction.rb
+++ b/lib/diaspora_federation/entities/relayable_retraction.rb
@@ -1,18 +1,18 @@
 module DiasporaFederation
   module Entities
-    # this entity represents a claim of deletion of a previously federated
-    # relayable entity ({Entities::Comment}, {Entities::Like})
+    # This entity represents a claim of deletion of a previously federated
+    # relayable entity. ({Entities::Comment}, {Entities::Like})
     #
     # There are two cases of federation of the RelayableRetraction.
     # Retraction from the dowstream object owner is when an author of the
-    # relayable (e.g. Comment) deletes it himself. In this case only target_author_signature
-    # is filled and retraction is sent to the commented post's author. Here
-    # he (upstream object owner) signes it with parent's author key and fills
-    # signature in parent_author_signature and sends it to other pods where
-    # other participating people present. This is the second case - retraction
+    # relayable (e.g. Comment) deletes it themself. In this case only target_author_signature
+    # is filled and a retraction is sent to the commented post's author. Here
+    # the upstream object owner signs it with the parent's author key, puts
+    # the signature in parent_author_signature and sends it to other pods where
+    # other participating people are present. This is the second case - retraction
     # from the upstream object owner.
     # Retraction from the upstream object owner can also be performed by the
-    # upstream object owner himself - he has a right to delete comments on his posts.
+    # upstream object owner themself - they have a right to delete comments on their posts.
     # In any case in the retraction by the upstream author target_author_signature
     # is not checked, only parent_author_signature is checked.
     #
@@ -20,33 +20,33 @@ module DiasporaFederation
     # @deprecated will be replaced with {Entities::Retraction}
     class RelayableRetraction < Entity
       # @!attribute [r] parent_author_signature
-      #   Contains a signature of the entity using the private key of the author of a parent post
-      #   This signature is mandatory only when federation from an upstream author to the subscribers.
+      #   Contains a signature of the entity using the private key of the author of a parent post.
+      #   This signature is mandatory only when federating from an upstream author to the subscribers.
       #   @see Relayable#parent_author_signature
       #   @return [String] parent author signature
       property :parent_author_signature, default: nil
 
       # @!attribute [r] target_guid
-      #   guid of a relayable to be deleted
+      #   Guid of a relayable to be deleted
       #   @see Comment#guid
       #   @return [String] target guid
       property :target_guid
 
       # @!attribute [r] target_type
-      #   a string describing a type of the target
+      #   A string describing a type of the target
       #   @see Retraction#target_type
       #   @return [String] target type
       property :target_type
 
       # @!attribute [r] author
-      #   The diaspora ID of the person who deletes a relayable
+      #   The diaspora* ID of the person who deletes a relayable
       #   @see Person#author
-      #   @return [String] diaspora ID
+      #   @return [String] diaspora* ID
       property :author, xml_name: :sender_handle
 
       # @!attribute [r] target_author_signature
       #   Contains a signature of the entity using the private key of the
-      #   author of a federated relayable entity ({Entities::Comment}, {Entities::Like})
+      #   author of a federated relayable entity. ({Entities::Comment}, {Entities::Like})
       #   This signature is mandatory only when federation from the subscriber to an upstream
       #   author is done.
       #   @see Relayable#author_signature
@@ -54,11 +54,11 @@ module DiasporaFederation
       property :target_author_signature, default: nil
 
       # @!attribute [r] target
-      #   target entity
+      #   Target entity
       #   @return [RelatedEntity] target entity
       entity :target, Entities::RelatedEntity
 
-      # use only {Retraction} for receive
+      # Use only {Retraction} for receive
       # @return [Retraction] instance as normal retraction
       def to_retraction
         Retraction.new(author: author, target_guid: target_guid, target_type: target_type, target: target)
diff --git a/lib/diaspora_federation/entities/request.rb b/lib/diaspora_federation/entities/request.rb
index 8db5340..096cc70 100644
--- a/lib/diaspora_federation/entities/request.rb
+++ b/lib/diaspora_federation/entities/request.rb
@@ -1,24 +1,24 @@
 module DiasporaFederation
   module Entities
-    # this entity represents a sharing request for a user. A user issues it
-    # when he starts sharing with another user.
+    # This entity represents a sharing request for a user. A user issues it
+    # when they start sharing with another user.
     #
     # @see Validators::RequestValidator
     # @deprecated will be replaced with {Contact}
     class Request < Entity
       # @!attribute [r] author
-      #   The diaspora ID of the person who shares his profile
+      #   The diaspora* ID of the person who share their profile
       #   @see Person#author
       #   @return [String] sender ID
       property :author, xml_name: :sender_handle
 
       # @!attribute [r] recipient
-      #   The diaspora ID of the person who will be shared with
+      #   The diaspora* ID of the person who will be shared with
       #   @see Validation::Rule::DiasporaId
       #   @return [String] recipient ID
       property :recipient, xml_name: :recipient_handle
 
-      # use only {Contact} for receive
+      # Use only {Contact} for receive
       # @return [Contact] instance as contact
       def to_contact
         Contact.new(author: author, recipient: recipient)
diff --git a/lib/diaspora_federation/entities/reshare.rb b/lib/diaspora_federation/entities/reshare.rb
index b03fd92..95f27d7 100644
--- a/lib/diaspora_federation/entities/reshare.rb
+++ b/lib/diaspora_federation/entities/reshare.rb
@@ -1,25 +1,25 @@
 module DiasporaFederation
   module Entities
-    # this entity represents the fact the a user reshared some other user's post
+    # This entity represents the fact that a user reshared another user's post.
     #
     # @see Validators::ReshareValidator
     class Reshare < Entity
       include Post
 
       # @!attribute [r] root_author
-      #   The diaspora ID of the person who posted the original post
+      #   The diaspora* ID of the person who posted the original post
       #   @see Person#author
-      #   @return [String] diaspora ID
+      #   @return [String] diaspora* ID
       property :root_author, xml_name: :root_diaspora_id
 
       # @!attribute [r] root_guid
-      #   guid of the original post
+      #   Guid of the original post
       #   @see StatusMessage#guid
       #   @return [String] root guid
       property :root_guid
 
       # @!attribute [r] public
-      #   has no meaning at the moment
+      #   Has no meaning at the moment
       #   @return [Boolean] public
       property :public, default: true # always true? (we only reshare public posts)
 
@@ -28,13 +28,13 @@ module DiasporaFederation
         "#{super}:#{root_guid}"
       end
 
-      # fetch and receive root post from remote, if not available locally.
+      # Fetch and receive root post from remote, if not available locally
       def fetch_root
         root = DiasporaFederation.callbacks.trigger(:fetch_related_entity, "Post", root_guid)
         Federation::Fetcher.fetch_public(root_author, "Post", root_guid) unless root
       end
 
-      # Fetch root post after parse.
+      # Fetch root post after parse
       # @see Entity.populate_entity
       # @param [Nokogiri::XML::Element] root_node xml nodes
       # @return [Entity] instance
diff --git a/lib/diaspora_federation/entities/retraction.rb b/lib/diaspora_federation/entities/retraction.rb
index 8d23bb6..c3db746 100644
--- a/lib/diaspora_federation/entities/retraction.rb
+++ b/lib/diaspora_federation/entities/retraction.rb
@@ -1,27 +1,27 @@
 module DiasporaFederation
   module Entities
-    # this entity represents a claim of deletion of a previously federated entity
+    # This entity represents a claim of deletion of a previously federated entity.
     #
     # @see Validators::RetractionValidator
     class Retraction < Entity
       # @!attribute [r] author
-      #   The diaspora ID of the person who deletes the entity
+      #   The diaspora* ID of the person who deletes the entity
       #   @see Person#author
-      #   @return [String] diaspora ID
+      #   @return [String] diaspora* ID
       property :author, xml_name: :diaspora_handle
 
       # @!attribute [r] target_guid
-      #   guid of the entity to be deleted
+      #   Guid of the entity to be deleted
       #   @return [String] target guid
       property :target_guid, xml_name: :post_guid
 
       # @!attribute [r] target_type
-      #   A string describing the type of the target.
+      #   A string describing the type of the target
       #   @return [String] target type
       property :target_type, xml_name: :type
 
       # @!attribute [r] target
-      #   target entity
+      #   Target entity
       #   @return [RelatedEntity] target entity
       entity :target, Entities::RelatedEntity
 
diff --git a/lib/diaspora_federation/entities/signed_retraction.rb b/lib/diaspora_federation/entities/signed_retraction.rb
index 33088e9..92a56f0 100644
--- a/lib/diaspora_federation/entities/signed_retraction.rb
+++ b/lib/diaspora_federation/entities/signed_retraction.rb
@@ -1,27 +1,27 @@
 module DiasporaFederation
   module Entities
-    # this entity represents a claim of deletion of a previously federated
-    # entity of post type ({Entities::StatusMessage})
+    # This entity represents a claim of deletion of a previously federated
+    # entity of post type. ({Entities::StatusMessage})
     #
     # @see Validators::SignedRetractionValidator
     # @deprecated will be replaced with {Entities::Retraction}
     class SignedRetraction < Entity
       # @!attribute [r] target_guid
-      #   guid of a post to be deleted
+      #   Guid of a post to be deleted
       #   @see Retraction#target_guid
       #   @return [String] target guid
       property :target_guid
 
       # @!attribute [r] target_type
-      #   A string describing the type of the target.
+      #   A string describing the type of the target
       #   @see Retraction#target_type
       #   @return [String] target type
       property :target_type
 
       # @!attribute [r] author
-      #   The diaspora ID of the person who deletes a post
+      #   The diaspora* ID of the person who deletes a post
       #   @see Person#author
-      #   @return [String] diaspora ID
+      #   @return [String] diaspora* ID
       property :author, xml_name: :sender_handle
 
       # @!attribute [r] author_signature
@@ -31,11 +31,11 @@ module DiasporaFederation
       property :target_author_signature, default: nil
 
       # @!attribute [r] target
-      #   target entity
+      #   Target entity
       #   @return [RelatedEntity] target entity
       entity :target, Entities::RelatedEntity
 
-      # use only {Retraction} for receive
+      # Use only {Retraction} for receive
       # @return [Retraction] instance as normal retraction
       def to_retraction
         Retraction.new(author: author, target_guid: target_guid, target_type: target_type, target: target)
diff --git a/lib/diaspora_federation/entities/status_message.rb b/lib/diaspora_federation/entities/status_message.rb
index f945565..e8dcbe4 100644
--- a/lib/diaspora_federation/entities/status_message.rb
+++ b/lib/diaspora_federation/entities/status_message.rb
@@ -1,33 +1,33 @@
 module DiasporaFederation
   module Entities
-    # this entity represents a status message sent by a user
+    # This entity represents a status message sent by a user.
     #
     # @see Validators::StatusMessageValidator
     class StatusMessage < Entity
       include Post
 
       # @!attribute [r] raw_message
-      #   text of the status message composed by the user
+      #   Text of the status message composed by the user
       #   @return [String] text of the status message
       property :raw_message
 
       # @!attribute [r] photos
-      #   optional photos attached to the status message
+      #   Optional photos attached to the status message
       #   @return [[Entities::Photo]] photos
       entity :photos, [Entities::Photo], default: []
 
       # @!attribute [r] location
-      #   optional location attached to the status message
+      #   Optional location attached to the status message
       #   @return [Entities::Location] location
       entity :location, Entities::Location, default: nil
 
       # @!attribute [r] poll
-      #   optional poll attached to the status message
+      #   Optional poll attached to the status message
       #   @return [Entities::Poll] poll
       entity :poll, Entities::Poll, default: nil
 
       # @!attribute [r] public
-      #   shows whether the status message is visible to everyone or only to some aspects
+      #   Shows whether the status message is visible to everyone or only to some aspects
       #   @return [Boolean] is it public
       property :public, default: false
 
diff --git a/lib/diaspora_federation/entity.rb b/lib/diaspora_federation/entity.rb
index 0605b05..77a936a 100644
--- a/lib/diaspora_federation/entity.rb
+++ b/lib/diaspora_federation/entity.rb
@@ -1,6 +1,6 @@
 module DiasporaFederation
   # +Entity+ is the base class for all other objects used to encapsulate data
-  # for federation messages in the Diaspora* network.
+  # for federation messages in the diaspora* network.
   # Entity fields are specified using a simple {PropertiesDSL DSL} as part of
   # the class definition.
   #
@@ -231,7 +231,7 @@ module DiasporaFederation
       end
     end
 
-    # create simple node, fill it with text and append to root
+    # Create simple node, fill it with text and append to root
     def simple_node(doc, name, value)
       xml_name = self.class.xml_names[name]
       Nokogiri::XML::Element.new(xml_name ? xml_name.to_s : name, doc).tap do |node|
@@ -268,7 +268,7 @@ module DiasporaFederation
       end
     end
 
-    # create simple entry in data hash
+    # Create simple entry in data hash
     #
     # @param [String] name xml tag to parse
     # @param [Nokogiri::XML::Element] root_node XML root_node to parse
@@ -279,7 +279,7 @@ module DiasporaFederation
       node.first.text if node.any?
     end
 
-    # create an entry in the data hash for the nested entity
+    # Create an entry in the data hash for the nested entity
     #
     # @param [Class] type target type to parse
     # @param [Nokogiri::XML::Element] root_node XML node to parse
@@ -289,7 +289,7 @@ module DiasporaFederation
       type.from_xml(node.first) if node.any?
     end
 
-    # collect all nested children of that type and create an array in the data hash
+    # Collect all nested children of that type and create an array in the data hash
     #
     # @param [Class] type target type to parse
     # @param [Nokogiri::XML::Element] root_node XML node to parse
diff --git a/lib/diaspora_federation/federation/fetcher.rb b/lib/diaspora_federation/federation/fetcher.rb
index cde5dd4..7963f51 100644
--- a/lib/diaspora_federation/federation/fetcher.rb
+++ b/lib/diaspora_federation/federation/fetcher.rb
@@ -1,9 +1,9 @@
 module DiasporaFederation
   module Federation
-    # this module is for fetching entities from other pods
+    # This module is for fetching entities from other pods.
     module Fetcher
-      # fetches a public entity from a remote pod
-      # @param [String] author the diaspora ID of the author of the entity
+      # Fetches a public entity from a remote pod
+      # @param [String] author the diaspora* ID of the author of the entity
       # @param [Symbol, String] entity_type snake_case version of the entity class
       # @param [String] guid guid of the entity to fetch
       def self.fetch_public(author, entity_type, guid)
diff --git a/lib/diaspora_federation/federation/receiver.rb b/lib/diaspora_federation/federation/receiver.rb
index 71b6686..cc4277f 100644
--- a/lib/diaspora_federation/federation/receiver.rb
+++ b/lib/diaspora_federation/federation/receiver.rb
@@ -1,10 +1,10 @@
 module DiasporaFederation
   module Federation
-    # this module is for parse and receive entities.
+    # This module parses and receives entities.
     module Receiver
       extend Logging
 
-      # receive a public message
+      # Receive a public message
       # @param [String] data message to receive
       # @param [Boolean] legacy use old slap parser
       def self.receive_public(data, legacy=false)
@@ -21,7 +21,7 @@ module DiasporaFederation
         raise e
       end
 
-      # receive a private message
+      # Receive a private message
       # @param [String] data message to receive
       # @param [OpenSSL::PKey::RSA] recipient_private_key recipient private key to decrypt the message
       # @param [Object] recipient_id the identifier to persist the entity for the correct user,
diff --git a/lib/diaspora_federation/federation/receiver/abstract_receiver.rb b/lib/diaspora_federation/federation/receiver/abstract_receiver.rb
index ec44773..9046139 100644
--- a/lib/diaspora_federation/federation/receiver/abstract_receiver.rb
+++ b/lib/diaspora_federation/federation/receiver/abstract_receiver.rb
@@ -1,11 +1,11 @@
 module DiasporaFederation
   module Federation
     module Receiver
-      # common functionality for receivers
+      # Common functionality for receivers
       class AbstractReceiver
         include Logging
 
-        # create a new receiver
+        # Creates a new receiver
         # @param [MagicEnvelope] magic_envelope the received magic envelope
         # @param [Object] recipient_id the identifier of the recipient of a private message
         def initialize(magic_envelope, recipient_id=nil)
@@ -14,7 +14,7 @@ module DiasporaFederation
           @recipient_id = recipient_id
         end
 
-        # validate and receive the entity
+        # Validates and receives the entity
         def receive
           validate_and_receive
         rescue => e
diff --git a/lib/diaspora_federation/federation/receiver/private.rb b/lib/diaspora_federation/federation/receiver/private.rb
index b6177dc..18115cf 100644
--- a/lib/diaspora_federation/federation/receiver/private.rb
+++ b/lib/diaspora_federation/federation/receiver/private.rb
@@ -1,7 +1,7 @@
 module DiasporaFederation
   module Federation
     module Receiver
-      # receiver for private entities
+      # Receiver for private entities
       class Private < AbstractReceiver
         private
 
diff --git a/lib/diaspora_federation/federation/receiver/public.rb b/lib/diaspora_federation/federation/receiver/public.rb
index d18fdfa..c4d1a8b 100644
--- a/lib/diaspora_federation/federation/receiver/public.rb
+++ b/lib/diaspora_federation/federation/receiver/public.rb
@@ -1,7 +1,7 @@
 module DiasporaFederation
   module Federation
     module Receiver
-      # receiver for public entities
+      # Receiver for public entities
       class Public < AbstractReceiver
         private
 
diff --git a/lib/diaspora_federation/http_client.rb b/lib/diaspora_federation/http_client.rb
index b8f068c..8cf0fa1 100644
--- a/lib/diaspora_federation/http_client.rb
+++ b/lib/diaspora_federation/http_client.rb
@@ -2,7 +2,7 @@ require "faraday"
 require "faraday_middleware/response/follow_redirects"
 
 module DiasporaFederation
-  # A wrapper for {https://github.com/lostisland/faraday Faraday}.
+  # A wrapper for {https://github.com/lostisland/faraday Faraday}
   #
   # @see Discovery::Discovery
   # @see Federation::Fetcher
@@ -15,7 +15,7 @@ module DiasporaFederation
       connection.get(uri)
     end
 
-    # gets the Faraday connection
+    # Gets the Faraday connection
     #
     # @return [Faraday::Connection] the response
     def self.connection
diff --git a/lib/diaspora_federation/logging.rb b/lib/diaspora_federation/logging.rb
index 7d65e19..4593c28 100644
--- a/lib/diaspora_federation/logging.rb
+++ b/lib/diaspora_federation/logging.rb
@@ -1,9 +1,9 @@
 module DiasporaFederation
-  # logging module for the diaspora federation
+  # Logging module for the diaspora* federation
   #
-  # it uses the logging-gem if available
+  # It uses the logging-gem if available.
   module Logging
-    # add +logger+ also as class method when included
+    # Add +logger+ also as class method when included
     # @param [Class] klass the class into which the module is included
     def self.included(klass)
       klass.extend(self)
@@ -11,15 +11,15 @@ module DiasporaFederation
 
     private
 
-    # get the logger for this class
+    # Get the logger for this class
     #
-    # use the logging-gem if available, else use a default logger
+    # Use the logging-gem if available, else use a default logger.
     def logger
       @logger ||= begin
-                    # use logging-gem if available
+                    # Use logging-gem if available
                     return ::Logging::Logger[self] if defined?(::Logging::Logger)
 
-                    # use rails logger if running in rails and no logging-gem is available
+                    # Use rails logger if running in rails and no logging-gem is available
                     return ::Rails.logger if defined?(::Rails)
 
                     # fallback logger
diff --git a/lib/diaspora_federation/properties_dsl.rb b/lib/diaspora_federation/properties_dsl.rb
index 744a7d8..24d28b5 100644
--- a/lib/diaspora_federation/properties_dsl.rb
+++ b/lib/diaspora_federation/properties_dsl.rb
@@ -75,7 +75,7 @@ module DiasporaFederation
       @xml_names ||= {}
     end
 
-    # finds a property by +xml_name+ or +name+
+    # Finds a property by +xml_name+ or +name+
     # @param [String] xml_name name of the property from the received xml
     # @return [Hash] the property data
     def find_property_for_xml_name(xml_name)
@@ -114,14 +114,14 @@ module DiasporaFederation
       define_alias(name, opts[:alias]) if opts.has_key? :alias
     end
 
-    # checks if the name is a +Symbol+ or a +String+
+    # 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)
     end
 
-    # checks if the type extends {Entity}
+    # Checks if the type extends {Entity}
     # @param [Class] type the type to check
     # @return [Boolean]
     def type_valid?(type)
diff --git a/lib/diaspora_federation/salmon.rb b/lib/diaspora_federation/salmon.rb
index 945bc53..79c0216 100644
--- a/lib/diaspora_federation/salmon.rb
+++ b/lib/diaspora_federation/salmon.rb
@@ -1,5 +1,5 @@
 module DiasporaFederation
-  # This module contains a Diaspora*-specific implementation of parts of the
+  # This module contains a diaspora*-specific implementation of parts of the
   # {http://www.salmon-protocol.org/ Salmon Protocol}.
   module Salmon
     # XML namespace url
diff --git a/lib/diaspora_federation/salmon/aes.rb b/lib/diaspora_federation/salmon/aes.rb
index d33c217..3ccf2ba 100644
--- a/lib/diaspora_federation/salmon/aes.rb
+++ b/lib/diaspora_federation/salmon/aes.rb
@@ -1,18 +1,18 @@
 module DiasporaFederation
   module Salmon
-    # class for AES encryption and decryption
+    # Class for AES encryption and decryption
     class AES
       # OpenSSL aes cipher definition
       CIPHER = "AES-256-CBC".freeze
 
-      # generates a random AES key and initialization vector
+      # Generates a random AES key and initialization vector
       # @return [Hash] { key: "...", iv: "..." }
       def self.generate_key_and_iv
         cipher = OpenSSL::Cipher.new(CIPHER)
         {key: cipher.random_key, iv: cipher.random_iv}
       end
 
-      # encrypts the given data with an AES cipher defined by the given key
+      # Encrypts the given data with an AES cipher defined by the given key
       # and iv and returns the resulting ciphertext base64 strict_encoded.
       # @param [String] data plain input
       # @param [String] key AES key
@@ -34,7 +34,7 @@ module DiasporaFederation
         Base64.strict_encode64(ciphertext)
       end
 
-      # decrypts the given ciphertext with an AES cipher defined by the given key
+      # Decrypts the given ciphertext with an AES cipher defined by the given key
       # and iv. +ciphertext+ is expected to be base64 encoded
       # @param [String] ciphertext input data
       # @param [String] key AES key
diff --git a/lib/diaspora_federation/salmon/encrypted_slap.rb b/lib/diaspora_federation/salmon/encrypted_slap.rb
index 997e88a..4acc4ef 100644
--- a/lib/diaspora_federation/salmon/encrypted_slap.rb
+++ b/lib/diaspora_federation/salmon/encrypted_slap.rb
@@ -3,14 +3,14 @@ require "json"
 module DiasporaFederation
   module Salmon
     # +EncryptedSlap+ provides class methods for generating and parsing encrypted
-    # Slaps. (In principle the same as  {Slap}, but with encryption.)
+    # Slaps. (In principle the same as {Slap}, but with encryption.)
     #
     # The basic encryption mechanism used here is based on the knowledge that
     # asymmetrical encryption is slow and symmetrical encryption is fast. Keeping in
     # mind that a message we want to de-/encrypt may greatly vary in length,
     # performance considerations must play a part of this scheme.
     #
-    # A Diaspora*-flavored encrypted magic-enveloped XML message looks like the following:
+    # A diaspora*-flavored encrypted magic-enveloped XML message looks like the following:
     #
     #   <?xml version="1.0" encoding="UTF-8"?>
     #   <diaspora xmlns="https://joindiaspora.com/protocol" xmlns:me="http://salmon-protocol.org/ns/magic-env">
@@ -63,7 +63,7 @@ module DiasporaFederation
     # @deprecated
     class EncryptedSlap < Slap
       # the author of the slap
-      # @param [String] value the author diaspora id
+      # @param [String] value the author diaspora* ID
       attr_writer :author_id
 
       # the key and iv if it is an encrypted slap
@@ -100,7 +100,7 @@ module DiasporaFederation
 
       # Creates an encrypted Salmon Slap.
       #
-      # @param [String] author_id Diaspora* handle of the author
+      # @param [String] author_id diaspora* ID of the author
       # @param [OpenSSL::PKey::RSA] privkey sender private key for signing the magic envelope
       # @param [Entity] entity payload
       # @return [EncryptedSlap] encrypted Slap instance
@@ -136,7 +136,7 @@ module DiasporaFederation
 
       private
 
-      # decrypts and reads the data from the encrypted XML header
+      # Decrypts and reads the data from the encrypted XML header
       # @param [String] data base64 encoded, encrypted header data
       # @param [OpenSSL::PKey::RSA] privkey private key for decryption
       # @return [Hash] { iv: "...", aes_key: "...", author_id: "..." }
@@ -151,7 +151,7 @@ module DiasporaFederation
         {iv: iv, aes_key: key, author_id: author_id}
       end
 
-      # decrypts the xml header
+      # Decrypts the xml header
       # @param [String] data base64 encoded, encrypted header data
       # @param [OpenSSL::PKey::RSA] privkey private key for decryption
       # @return [Nokogiri::XML::Element] header xml document
@@ -163,8 +163,8 @@ module DiasporaFederation
         Nokogiri::XML::Document.parse(xml).root
       end
 
-      # encrypt the header xml with an AES cipher and encrypt the cipher params
-      # with the recipients public_key
+      # Encrypt the header xml with an AES cipher and encrypt the cipher params
+      # with the recipients public_key.
       # @param [String] author_id diaspora_handle
       # @param [Hash] envelope_key envelope cipher params
       # @param [OpenSSL::PKey::RSA] pubkey recipient public_key
@@ -182,7 +182,7 @@ module DiasporaFederation
         Base64.strict_encode64(json_header)
       end
 
-      # generate the header xml string, including the author, aes_key and iv
+      # Generate the header xml string, including the author, aes_key and iv
       # @param [String] author_id diaspora_handle of the author
       # @param [Hash] envelope_key { key: "...", iv: "..." } (values in base64)
       # @return [String] header XML string
diff --git a/lib/diaspora_federation/salmon/magic_envelope.rb b/lib/diaspora_federation/salmon/magic_envelope.rb
index 840dfe3..dcd9822 100644
--- a/lib/diaspora_federation/salmon/magic_envelope.rb
+++ b/lib/diaspora_federation/salmon/magic_envelope.rb
@@ -1,6 +1,6 @@
 module DiasporaFederation
   module Salmon
-    # Represents a Magic Envelope for Diaspora* federation messages.
+    # Represents a Magic Envelope for diaspora* federation messages
     #
     # When generating a Magic Envelope, an instance of this class is created and
     # the contents are specified on initialization. Optionally, the payload can be
@@ -23,26 +23,26 @@ module DiasporaFederation
     class MagicEnvelope
       include Logging
 
-      # encoding used for the payload data
+      # Encoding used for the payload data
       ENCODING = "base64url".freeze
 
-      # algorithm used for signing the payload data
+      # Algorithm used for signing the payload data
       ALGORITHM = "RSA-SHA256".freeze
 
-      # mime type describing the payload data
+      # Mime type describing the payload data
       DATA_TYPE = "application/xml".freeze
 
-      # digest instance used for signing
+      # Digest instance used for signing
       DIGEST = OpenSSL::Digest::SHA256.new
 
       # XML namespace url
       XMLNS = "http://salmon-protocol.org/ns/magic-env".freeze
 
-      # the payload entity of the magic envelope
+      # The payload entity of the magic envelope
       # @return [Entity] payload entity
       attr_reader :payload
 
-      # the sender of the magic envelope
+      # The sender of the magic envelope
       # @return [String] diaspora-ID of the sender
       attr_reader :sender
 
@@ -101,7 +101,7 @@ module DiasporaFederation
       # @see AES#decrypt
       #
       # @param [Nokogiri::XML::Element] magic_env XML root node of a magic envelope
-      # @param [String] sender diaspora-ID of the sender or nil
+      # @param [String] sender diaspora* ID of the sender or nil
       # @param [Hash] cipher_params hash containing the key and iv for
       #   AES-decrypting previously encrypted data. E.g.: { iv: "...", key: "..." }
       #
@@ -132,7 +132,7 @@ module DiasporaFederation
 
       private
 
-      # the payload data as string
+      # The payload data as string
       # @return [String] payload data
       def payload_data
         @payload_data ||= XmlPayload.pack(@payload).to_xml.strip.tap do |data|
@@ -155,7 +155,7 @@ module DiasporaFederation
         }.doc.root
       end
 
-      # create the signature for all fields according to specification
+      # Creates the signature for all fields according to specification
       #
       # @param [OpenSSL::PKey::RSA] privkey private key used for signing
       # @return [String] the signature
@@ -173,7 +173,7 @@ module DiasporaFederation
       end
 
       # @param [Nokogiri::XML::Element] env magic envelope XML
-      # @param [String] sender diaspora-ID of the sender or nil
+      # @param [String] sender diaspora* ID of the sender or nil
       # @return [Boolean]
       private_class_method def self.signature_valid?(env, sender)
         subject = sig_subject([Base64.urlsafe_decode64(env.at_xpath("me:data").content),
@@ -188,18 +188,18 @@ module DiasporaFederation
         sender_key.verify(DIGEST, sig, subject)
       end
 
-      # reads the +key_id+ from the magic envelope
+      # Reads the +key_id+ from the magic envelope.
       # @param [Nokogiri::XML::Element] env magic envelope XML
-      # @return [String] diaspora-ID of the sender
+      # @return [String] diaspora* ID of the sender
       private_class_method def self.sender(env)
         key_id = env.at_xpath("me:sig")["key_id"]
         raise InvalidEnvelope, "no key_id" unless key_id # TODO: move to `envelope_valid?`
         Base64.urlsafe_decode64(key_id)
       end
 
-      # constructs the signature subject.
-      # the given array should consist of the data, data_type (mimetype), encoding
-      # and the algorithm
+      # Constructs the signature subject.
+      # The given array should consist of the data, data_type (mimetype), encoding
+      # and the algorithm.
       # @param [Array<String>] data_arr
       # @return [String] signature subject
       private_class_method def self.sig_subject(data_arr)
diff --git a/lib/diaspora_federation/salmon/slap.rb b/lib/diaspora_federation/salmon/slap.rb
index 55ac8f3..958550a 100644
--- a/lib/diaspora_federation/salmon/slap.rb
+++ b/lib/diaspora_federation/salmon/slap.rb
@@ -3,7 +3,7 @@ module DiasporaFederation
     # +Slap+ provides class methods to create unencrypted Slap XML from payload
     # data and parse incoming XML into a Slap instance.
     #
-    # A Diaspora*-flavored magic-enveloped XML message looks like the following:
+    # A diaspora* flavored magic-enveloped XML message looks like the following:
     #
     #   <?xml version="1.0" encoding="UTF-8"?>
     #   <diaspora xmlns="https://joindiaspora.com/protocol" xmlns:me="http://salmon-protocol.org/ns/magic-env">
@@ -51,7 +51,7 @@ module DiasporaFederation
 
       # Creates an unencrypted Salmon Slap and returns the XML string.
       #
-      # @param [String] author_id Diaspora* handle of the author
+      # @param [String] author_id diaspora* ID of the author
       # @param [OpenSSL::PKey::RSA] privkey sender private_key for signing the magic envelope
       # @param [Entity] entity payload
       # @return [String] Salmon XML string
diff --git a/lib/diaspora_federation/test.rb b/lib/diaspora_federation/test.rb
index 2bb9d5a..249c9d9 100644
--- a/lib/diaspora_federation/test.rb
+++ b/lib/diaspora_federation/test.rb
@@ -1,7 +1,7 @@
 require "diaspora_federation/test/factories"
 
 module DiasporaFederation
-  # This module encapsulates helper functions maybe wanted by a testsuite of a diaspora_federation gem user application
+  # This module encapsulates helper functions maybe wanted by a testsuite of a diaspora_federation gem user application.
   module Test
   end
 end
diff --git a/lib/diaspora_federation/test/factories.rb b/lib/diaspora_federation/test/factories.rb
index bf5a4d7..3d535cf 100644
--- a/lib/diaspora_federation/test/factories.rb
+++ b/lib/diaspora_federation/test/factories.rb
@@ -5,7 +5,7 @@ module DiasporaFederation
   module Test
     # Factories for federation entities
     module Factories
-      # defines the federation entity factories
+      # Defines the federation entity factories
       def self.federation_factories
         FactoryGirl.define do
           initialize_with { new(attributes) }
diff --git a/lib/diaspora_federation/validators.rb b/lib/diaspora_federation/validators.rb
index a2de867..e9c54f5 100644
--- a/lib/diaspora_federation/validators.rb
+++ b/lib/diaspora_federation/validators.rb
@@ -9,7 +9,7 @@ require "validation/rule/numeric"
 module Validation
   # This module contains custom validation rules for various data field types.
   # That includes types for which there are no provided rules by the +valid+ gem
-  # or types that are very specific to Diaspora* federation and need special handling.
+  # or types that are very specific to diaspora* federation and need special handling.
   # The rules are used inside the {DiasporaFederation::Validators validator classes}
   # to perform basic sanity-checks on {DiasporaFederation::Entities federation entities}.
   module Rule
diff --git a/lib/diaspora_federation/validators/account_deletion_validator.rb b/lib/diaspora_federation/validators/account_deletion_validator.rb
index a52401c..6f7ceac 100644
--- a/lib/diaspora_federation/validators/account_deletion_validator.rb
+++ b/lib/diaspora_federation/validators/account_deletion_validator.rb
@@ -1,6 +1,6 @@
 module DiasporaFederation
   module Validators
-    # This validates a {Entities::AccountDeletion}
+    # This validates a {Entities::AccountDeletion}.
     class AccountDeletionValidator < Validation::Validator
       include Validation
 
diff --git a/lib/diaspora_federation/validators/comment_validator.rb b/lib/diaspora_federation/validators/comment_validator.rb
index eb015f9..8f49518 100644
--- a/lib/diaspora_federation/validators/comment_validator.rb
+++ b/lib/diaspora_federation/validators/comment_validator.rb
@@ -1,6 +1,6 @@
 module DiasporaFederation
   module Validators
-    # This validates a {Entities::Comment}
+    # This validates a {Entities::Comment}.
     class CommentValidator < Validation::Validator
       include Validation
 
diff --git a/lib/diaspora_federation/validators/contact_validator.rb b/lib/diaspora_federation/validators/contact_validator.rb
index 5923cd3..e223c73 100644
--- a/lib/diaspora_federation/validators/contact_validator.rb
+++ b/lib/diaspora_federation/validators/contact_validator.rb
@@ -1,6 +1,6 @@
 module DiasporaFederation
   module Validators
-    # This validates a {Entities::Contact}
+    # This validates a {Entities::Contact}.
     class ContactValidator < Validation::Validator
       include Validation
 
diff --git a/lib/diaspora_federation/validators/conversation_validator.rb b/lib/diaspora_federation/validators/conversation_validator.rb
index 35a8c04..0001787 100644
--- a/lib/diaspora_federation/validators/conversation_validator.rb
+++ b/lib/diaspora_federation/validators/conversation_validator.rb
@@ -1,6 +1,6 @@
 module DiasporaFederation
   module Validators
-    # This validates a {Entities::Conversation}
+    # This validates a {Entities::Conversation}.
     class ConversationValidator < Validation::Validator
       include Validation
 
diff --git a/lib/diaspora_federation/validators/h_card_validator.rb b/lib/diaspora_federation/validators/h_card_validator.rb
index 8fce42d..1803bc9 100644
--- a/lib/diaspora_federation/validators/h_card_validator.rb
+++ b/lib/diaspora_federation/validators/h_card_validator.rb
@@ -1,6 +1,6 @@
 module DiasporaFederation
   module Validators
-    # This validates a {Discovery::HCard}
+    # This validates a {Discovery::HCard}.
     #
     # @todo activate guid and public key validation after all pod have it in
     #   the hcard.
@@ -11,7 +11,7 @@ module DiasporaFederation
 
       # rule :guid, :guid
 
-      # the name must not contain a semicolon because of mentions
+      # The name must not contain a semicolon because of mentions.
       # @{<full_name> ; <diaspora_id>}
       rule :full_name, regular_expression: {regex: /\A[^;]{,70}\z/}
       rule :first_name, regular_expression: {regex: /\A[^;]{,32}\z/}
diff --git a/lib/diaspora_federation/validators/like_validator.rb b/lib/diaspora_federation/validators/like_validator.rb
index 6637f83..1f1d13e 100644
--- a/lib/diaspora_federation/validators/like_validator.rb
+++ b/lib/diaspora_federation/validators/like_validator.rb
@@ -1,6 +1,6 @@
 module DiasporaFederation
   module Validators
-    # This validates a {Entities::Like}
+    # This validates a {Entities::Like}.
     class LikeValidator < Validation::Validator
       include Validation
 
diff --git a/lib/diaspora_federation/validators/location_validator.rb b/lib/diaspora_federation/validators/location_validator.rb
index 8ecfd6e..beb268b 100644
--- a/lib/diaspora_federation/validators/location_validator.rb
+++ b/lib/diaspora_federation/validators/location_validator.rb
@@ -1,6 +1,6 @@
 module DiasporaFederation
   module Validators
-    # This validates a {Entities::Location}
+    # This validates a {Entities::Location}.
     class LocationValidator < Validation::Validator
       include Validation
 
diff --git a/lib/diaspora_federation/validators/message_validator.rb b/lib/diaspora_federation/validators/message_validator.rb
index fd1c478..5473ded 100644
--- a/lib/diaspora_federation/validators/message_validator.rb
+++ b/lib/diaspora_federation/validators/message_validator.rb
@@ -1,6 +1,6 @@
 module DiasporaFederation
   module Validators
-    # This validates a {Entities::Message}
+    # This validates a {Entities::Message}.
     class MessageValidator < Validation::Validator
       include Validation
 
diff --git a/lib/diaspora_federation/validators/participation_validator.rb b/lib/diaspora_federation/validators/participation_validator.rb
index 5fc5c87..7b63b07 100644
--- a/lib/diaspora_federation/validators/participation_validator.rb
+++ b/lib/diaspora_federation/validators/participation_validator.rb
@@ -1,6 +1,6 @@
 module DiasporaFederation
   module Validators
-    # This validates a {Entities::Participation}
+    # This validates a {Entities::Participation}.
     class ParticipationValidator < Validation::Validator
       include Validation
 
diff --git a/lib/diaspora_federation/validators/person_validator.rb b/lib/diaspora_federation/validators/person_validator.rb
index 6d875df..b474439 100644
--- a/lib/diaspora_federation/validators/person_validator.rb
+++ b/lib/diaspora_federation/validators/person_validator.rb
@@ -1,6 +1,6 @@
 module DiasporaFederation
   module Validators
-    # This validates a {Entities::Person}
+    # This validates a {Entities::Person}.
     class PersonValidator < Validation::Validator
       include Validation
 
diff --git a/lib/diaspora_federation/validators/photo_validator.rb b/lib/diaspora_federation/validators/photo_validator.rb
index fa68099..af9f5f1 100644
--- a/lib/diaspora_federation/validators/photo_validator.rb
+++ b/lib/diaspora_federation/validators/photo_validator.rb
@@ -1,6 +1,6 @@
 module DiasporaFederation
   module Validators
-    # This validates a {Entities::Photo}
+    # This validates a {Entities::Photo}.
     class PhotoValidator < Validation::Validator
       include Validation
 
diff --git a/lib/diaspora_federation/validators/poll_answer_validator.rb b/lib/diaspora_federation/validators/poll_answer_validator.rb
index fd727ae..76a7e20 100644
--- a/lib/diaspora_federation/validators/poll_answer_validator.rb
+++ b/lib/diaspora_federation/validators/poll_answer_validator.rb
@@ -1,6 +1,6 @@
 module DiasporaFederation
   module Validators
-    # This validates a {Entities::PollAnswer}
+    # This validates a {Entities::PollAnswer}.
     class PollAnswerValidator < Validation::Validator
       include Validation
 
diff --git a/lib/diaspora_federation/validators/poll_participation_validator.rb b/lib/diaspora_federation/validators/poll_participation_validator.rb
index fa80692..56e91ea 100644
--- a/lib/diaspora_federation/validators/poll_participation_validator.rb
+++ b/lib/diaspora_federation/validators/poll_participation_validator.rb
@@ -1,6 +1,6 @@
 module DiasporaFederation
   module Validators
-    # This validates a {Entities::PollParticipation}
+    # This validates a {Entities::PollParticipation}.
     class PollParticipationValidator < Validation::Validator
       include Validation
 
diff --git a/lib/diaspora_federation/validators/poll_validator.rb b/lib/diaspora_federation/validators/poll_validator.rb
index f1d598f..9041e45 100644
--- a/lib/diaspora_federation/validators/poll_validator.rb
+++ b/lib/diaspora_federation/validators/poll_validator.rb
@@ -1,6 +1,6 @@
 module DiasporaFederation
   module Validators
-    # This validates a {Entities::Poll}
+    # This validates a {Entities::Poll}.
     class PollValidator < Validation::Validator
       include Validation
 
diff --git a/lib/diaspora_federation/validators/profile_validator.rb b/lib/diaspora_federation/validators/profile_validator.rb
index 727ae31..fabe407 100644
--- a/lib/diaspora_federation/validators/profile_validator.rb
+++ b/lib/diaspora_federation/validators/profile_validator.rb
@@ -1,17 +1,17 @@
 module DiasporaFederation
   module Validators
-    # This validates a {Entities::Profile}
+    # This validates a {Entities::Profile}.
     class ProfileValidator < Validation::Validator
       include Validation
 
       rule :author, :diaspora_id
 
-      # the name must not contain a semicolon because of mentions
+      # The name must not contain a semicolon because of mentions.
       # @{<full_name> ; <diaspora_id>}
       rule :first_name, regular_expression: {regex: /\A[^;]{,32}\z/}
       rule :last_name, regular_expression: {regex: /\A[^;]{,32}\z/}
 
-      # this urls can be relative
+      # These urls can be relative.
       rule :image_url, URI: [:path]
       rule :image_url_medium, URI: [:path]
       rule :image_url_small, URI: [:path]
diff --git a/lib/diaspora_federation/validators/related_entity_validator.rb b/lib/diaspora_federation/validators/related_entity_validator.rb
index 064564c..2fddb20 100644
--- a/lib/diaspora_federation/validators/related_entity_validator.rb
+++ b/lib/diaspora_federation/validators/related_entity_validator.rb
@@ -1,6 +1,6 @@
 module DiasporaFederation
   module Validators
-    # This validates a {Entities::RelatedEntity}
+    # This validates a {Entities::RelatedEntity}.
     class RelatedEntityValidator < Validation::Validator
       include Validation
 
diff --git a/lib/diaspora_federation/validators/relayable_retraction_validator.rb b/lib/diaspora_federation/validators/relayable_retraction_validator.rb
index c062f15..be5e4ad 100644
--- a/lib/diaspora_federation/validators/relayable_retraction_validator.rb
+++ b/lib/diaspora_federation/validators/relayable_retraction_validator.rb
@@ -1,7 +1,7 @@
 module DiasporaFederation
   module Validators
-    # This validates a {Entities::RelayableRetraction}
-    # @deprecated the {Entities::RelayableRetraction} will be replaced with {Entities::Retraction}
+    # This validates a {Entities::RelayableRetraction}.
+    # @deprecated The {Entities::RelayableRetraction} will be replaced with {Entities::Retraction}.
     class RelayableRetractionValidator < Validation::Validator
       include Validation
 
diff --git a/lib/diaspora_federation/validators/relayable_validator.rb b/lib/diaspora_federation/validators/relayable_validator.rb
index 3f14195..af7a6ef 100644
--- a/lib/diaspora_federation/validators/relayable_validator.rb
+++ b/lib/diaspora_federation/validators/relayable_validator.rb
@@ -1,8 +1,8 @@
 module DiasporaFederation
   module Validators
-    # This is included to validatros which validate entities which include {Entities::Relayable}
+    # This is included to validatros which validate entities which include {Entities::Relayable}.
     module RelayableValidator
-      # when this module is included in a Validator child it adds rules for relayable validation
+      # When this module is included in a Validator child it adds rules for relayable validation.
       # @param [Validation::Validator] validator the validator in which it is included
       def self.included(validator)
         validator.class_eval do
diff --git a/lib/diaspora_federation/validators/request_validator.rb b/lib/diaspora_federation/validators/request_validator.rb
index 3f7f5c6..9a10300 100644
--- a/lib/diaspora_federation/validators/request_validator.rb
+++ b/lib/diaspora_federation/validators/request_validator.rb
@@ -1,7 +1,7 @@
 module DiasporaFederation
   module Validators
-    # This validates a {Entities::Request}
-    # @deprecated the {Entities::Request} will be replaced with {Entities::Contact}
+    # This validates a {Entities::Request}.
+    # @deprecated The {Entities::Request} will be replaced with {Entities::Contact}.
     class RequestValidator < Validation::Validator
       include Validation
 
diff --git a/lib/diaspora_federation/validators/reshare_validator.rb b/lib/diaspora_federation/validators/reshare_validator.rb
index 0cb1ec1..d228106 100644
--- a/lib/diaspora_federation/validators/reshare_validator.rb
+++ b/lib/diaspora_federation/validators/reshare_validator.rb
@@ -1,6 +1,6 @@
 module DiasporaFederation
   module Validators
-    # This validates a {Entities::Reshare}
+    # This validates a {Entities::Reshare}.
     class ReshareValidator < Validation::Validator
       include Validation
 
diff --git a/lib/diaspora_federation/validators/retraction_validator.rb b/lib/diaspora_federation/validators/retraction_validator.rb
index fd621ec..dc942e4 100644
--- a/lib/diaspora_federation/validators/retraction_validator.rb
+++ b/lib/diaspora_federation/validators/retraction_validator.rb
@@ -1,6 +1,6 @@
 module DiasporaFederation
   module Validators
-    # This validates a {Entities::Retraction}
+    # This validates a {Entities::Retraction}.
     class RetractionValidator < Validation::Validator
       include Validation
 
diff --git a/lib/diaspora_federation/validators/rules/birthday.rb b/lib/diaspora_federation/validators/rules/birthday.rb
index 682719c..c780f34 100644
--- a/lib/diaspora_federation/validators/rules/birthday.rb
+++ b/lib/diaspora_federation/validators/rules/birthday.rb
@@ -15,7 +15,7 @@ module Validation
         :birthday
       end
 
-      # Determines if value is a valid birthday date
+      # 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
@@ -28,7 +28,7 @@ module Validation
         false
       end
 
-      # This rule has no params
+      # This rule has no params.
       # @return [Hash] params
       def params
         {}
diff --git a/lib/diaspora_federation/validators/rules/boolean.rb b/lib/diaspora_federation/validators/rules/boolean.rb
index f2f4918..2a2387e 100644
--- a/lib/diaspora_federation/validators/rules/boolean.rb
+++ b/lib/diaspora_federation/validators/rules/boolean.rb
@@ -28,7 +28,7 @@ module Validation
         end
       end
 
-      # This rule has no params
+      # This rule has no params.
       # @return [Hash] params
       def params
         {}
diff --git a/lib/diaspora_federation/validators/rules/diaspora_id.rb b/lib/diaspora_federation/validators/rules/diaspora_id.rb
index a57ee47..001face 100644
--- a/lib/diaspora_federation/validators/rules/diaspora_id.rb
+++ b/lib/diaspora_federation/validators/rules/diaspora_id.rb
@@ -1,10 +1,10 @@
 module Validation
   module Rule
-    # Diaspora ID validation rule
+    # diaspora* ID validation rule
     #
-    # A simple rule to validate the base structure of diaspora IDs.
+    # A simple rule to validate the base structure of diaspora* IDs.
     class DiasporaId
-      # The Regex for a valid diaspora ID
+      # The Regex for a valid diaspora* ID
       DIASPORA_ID = begin
         letter         = "a-zA-Z"
         digit          = "0-9"
@@ -28,12 +28,12 @@ module Validation
         :diaspora_id
       end
 
-      # Determines if value is a valid diaspora ID
+      # Determines if value is a valid diaspora* ID
       def valid_value?(value)
         value.nil? || !DIASPORA_ID.match(value).nil?
       end
 
-      # This rule has no params
+      # This rule has no params.
       # @return [Hash] params
       def params
         {}
diff --git a/lib/diaspora_federation/validators/rules/diaspora_id_count.rb b/lib/diaspora_federation/validators/rules/diaspora_id_count.rb
index 35fa189..e337cec 100644
--- a/lib/diaspora_federation/validators/rules/diaspora_id_count.rb
+++ b/lib/diaspora_federation/validators/rules/diaspora_id_count.rb
@@ -1,13 +1,13 @@
 module Validation
   module Rule
-    # Rule for validating the number of Diaspora* ids in a string.
+    # Rule for validating the number of diaspora* IDs in a string.
     # The evaluated string is split at ";" and the result will be counted.
     class DiasporaIdCount
-      # This rule must have a +maximum+ param
+      # This rule must have a +maximum+ param.
       # @return [Hash] params
       attr_reader :params
 
-      # create a new rule for a maximum diaspora id count validation
+      # Creates a new rule for a maximum diaspora* ID count validation
       # @param [Hash] params
       # @option params [Fixnum] :maximum maximum allowed id count
       def initialize(params)
diff --git a/lib/diaspora_federation/validators/rules/guid.rb b/lib/diaspora_federation/validators/rules/guid.rb
index 821f0a5..63f1224 100644
--- a/lib/diaspora_federation/validators/rules/guid.rb
+++ b/lib/diaspora_federation/validators/rules/guid.rb
@@ -7,11 +7,11 @@ module Validation
     # * Numbers: 0-9
     # * Special chars: '-', '_', '@', '.' and ':'
     class Guid
-      # This rule can have a +nilable+ param
+      # This rule can have a +nilable+ param.
       # @return [Hash] params
       attr_reader :params
 
-      # create a new rule for guid validation
+      # Creates a new rule for guid validation
       # @param [Hash] params
       # @option params [Boolean] :nilable guid allowed to be nil
       def initialize(params={})
diff --git a/lib/diaspora_federation/validators/rules/not_nil.rb b/lib/diaspora_federation/validators/rules/not_nil.rb
index 8d37d7e..3fb6950 100644
--- a/lib/diaspora_federation/validators/rules/not_nil.rb
+++ b/lib/diaspora_federation/validators/rules/not_nil.rb
@@ -13,7 +13,7 @@ module Validation
         !value.nil?
       end
 
-      # This rule has no params
+      # This rule has no params.
       # @return [Hash] params
       def params
         {}
diff --git a/lib/diaspora_federation/validators/rules/public_key.rb b/lib/diaspora_federation/validators/rules/public_key.rb
index 8601fc9..7b94802 100644
--- a/lib/diaspora_federation/validators/rules/public_key.rb
+++ b/lib/diaspora_federation/validators/rules/public_key.rb
@@ -23,7 +23,7 @@ module Validation
         )
       end
 
-      # This rule has no params
+      # This rule has no params.
       # @return [Hash] params
       def params
         {}
diff --git a/lib/diaspora_federation/validators/rules/tag_count.rb b/lib/diaspora_federation/validators/rules/tag_count.rb
index 3eb4120..7df9e03 100644
--- a/lib/diaspora_federation/validators/rules/tag_count.rb
+++ b/lib/diaspora_federation/validators/rules/tag_count.rb
@@ -4,11 +4,11 @@ module Validation
     # Only the "#" characters will be counted.
     # The string can be nil.
     class TagCount
-      # This rule must have a +maximum+ param
+      # This rule must have a +maximum+ param.
       # @return [Hash] params
       attr_reader :params
 
-      # create a new rule for a maximum tag count validation
+      # Creates a new rule for a maximum tag count validation
       # @param [Hash] params
       # @option params [Fixnum] :maximum maximum allowed tag count
       def initialize(params)
diff --git a/lib/diaspora_federation/validators/signed_retraction_validator.rb b/lib/diaspora_federation/validators/signed_retraction_validator.rb
index 9e3c2f8..414784f 100644
--- a/lib/diaspora_federation/validators/signed_retraction_validator.rb
+++ b/lib/diaspora_federation/validators/signed_retraction_validator.rb
@@ -1,7 +1,7 @@
 module DiasporaFederation
   module Validators
-    # This validates a {Entities::SignedRetraction}
-    # @deprecated the {Entities::RelayableRetraction} will be replaced with {Entities::Retraction}
+    # This validates a {Entities::SignedRetraction}.
+    # @deprecated The {Entities::RelayableRetraction} will be replaced with {Entities::Retraction}.
     class SignedRetractionValidator < Validation::Validator
       include Validation
 
diff --git a/lib/diaspora_federation/validators/status_message_validator.rb b/lib/diaspora_federation/validators/status_message_validator.rb
index 03df263..dabe3ef 100644
--- a/lib/diaspora_federation/validators/status_message_validator.rb
+++ b/lib/diaspora_federation/validators/status_message_validator.rb
@@ -1,6 +1,6 @@
 module DiasporaFederation
   module Validators
-    # This validates a {Entities::StatusMessage}
+    # This validates a {Entities::StatusMessage}.
     class StatusMessageValidator < Validation::Validator
       include Validation
 
diff --git a/lib/diaspora_federation/validators/web_finger_validator.rb b/lib/diaspora_federation/validators/web_finger_validator.rb
index b701169..e4bc298 100644
--- a/lib/diaspora_federation/validators/web_finger_validator.rb
+++ b/lib/diaspora_federation/validators/web_finger_validator.rb
@@ -1,9 +1,9 @@
 module DiasporaFederation
   module Validators
-    # This validates a {Discovery::WebFinger}
+    # This validates a {Discovery::WebFinger}.
     #
-    # @note it does not validate the guid and public key, because it will be
-    #   removed in the webfinger
+    # @note It does not validate the guid and public key, because it will be
+    #   removed in the webfinger.
     class WebFingerValidator < Validation::Validator
       include Validation
 
diff --git a/spec/controllers/diaspora_federation/webfinger_controller_spec.rb b/spec/controllers/diaspora_federation/webfinger_controller_spec.rb
index 8c8c946..38577ad 100644
--- a/spec/controllers/diaspora_federation/webfinger_controller_spec.rb
+++ b/spec/controllers/diaspora_federation/webfinger_controller_spec.rb
@@ -48,7 +48,7 @@ module DiasporaFederation
         expect(response).to be_success
       end
 
-      it "contains the diaspora id" do
+      it "contains the diaspora* ID" do
         get :legacy_webfinger, "q" => "acct:alice@localhost:3000"
         expect(response.body).to include "<Subject>acct:alice@localhost:3000</Subject>"
       end
diff --git a/spec/lib/diaspora_federation/discovery/discovery_spec.rb b/spec/lib/diaspora_federation/discovery/discovery_spec.rb
index 8fc1868..84b802f 100644
--- a/spec/lib/diaspora_federation/discovery/discovery_spec.rb
+++ b/spec/lib/diaspora_federation/discovery/discovery_spec.rb
@@ -7,7 +7,7 @@ module DiasporaFederation
     let(:default_image) { "http://localhost:3000/assets/user/default.png" }
 
     describe "#intialize" do
-      it "sets diaspora id" do
+      it "sets diaspora* ID" do
         discovery = Discovery::Discovery.new("some_user@example.com")
         expect(discovery.diaspora_id).to eq("some_user@example.com")
       end
@@ -95,7 +95,7 @@ module DiasporaFederation
         expect(person.diaspora_id).to eq(account)
       end
 
-      it "fails if the diaspora id does not match" do
+      it "fails if the diaspora* ID does not match" do
         modified_webfinger = webfinger_xrd.gsub(account, "anonther_user@example.com")
 
         stub_request(:get, "https://localhost:3000/.well-known/host-meta")
@@ -106,7 +106,7 @@ module DiasporaFederation
         expect { Discovery::Discovery.new(account).fetch_and_save }.to raise_error Discovery::DiscoveryError
       end
 
-      it "fails if the diaspora id was not found" do
+      it "fails if the diaspora* ID was not found" do
         stub_request(:get, "https://localhost:3000/.well-known/host-meta")
           .to_return(status: 200, body: host_meta_xrd)
         stub_request(:get, "http://localhost:3000/webfinger?q=acct:#{account}")
diff --git a/spec/lib/diaspora_federation/validators/account_deletion_validator_spec.rb b/spec/lib/diaspora_federation/validators/account_deletion_validator_spec.rb
index 5f48f78..7d0b542 100644
--- a/spec/lib/diaspora_federation/validators/account_deletion_validator_spec.rb
+++ b/spec/lib/diaspora_federation/validators/account_deletion_validator_spec.rb
@@ -4,7 +4,7 @@ module DiasporaFederation
 
     it_behaves_like "a common validator"
 
-    it_behaves_like "a diaspora id validator" do
+    it_behaves_like "a diaspora* ID validator" do
       let(:property) { :author }
       let(:mandatory) { true }
     end
diff --git a/spec/lib/diaspora_federation/validators/contact_validator_spec.rb b/spec/lib/diaspora_federation/validators/contact_validator_spec.rb
index 128dd0e..e939faa 100644
--- a/spec/lib/diaspora_federation/validators/contact_validator_spec.rb
+++ b/spec/lib/diaspora_federation/validators/contact_validator_spec.rb
@@ -6,7 +6,7 @@ module DiasporaFederation
 
     %i(author recipient).each do |prop|
       describe "##{prop}" do
-        it_behaves_like "a diaspora id validator" do
+        it_behaves_like "a diaspora* ID validator" do
           let(:property) { prop }
           let(:mandatory) { true }
         end
diff --git a/spec/lib/diaspora_federation/validators/conversation_validator_spec.rb b/spec/lib/diaspora_federation/validators/conversation_validator_spec.rb
index 4def7a0..ee2e221 100644
--- a/spec/lib/diaspora_federation/validators/conversation_validator_spec.rb
+++ b/spec/lib/diaspora_federation/validators/conversation_validator_spec.rb
@@ -4,7 +4,7 @@ module DiasporaFederation
 
     it_behaves_like "a common validator"
 
-    it_behaves_like "a diaspora id validator" do
+    it_behaves_like "a diaspora* ID validator" do
       let(:property) { :author }
       let(:mandatory) { true }
     end
diff --git a/spec/lib/diaspora_federation/validators/message_validator_spec.rb b/spec/lib/diaspora_federation/validators/message_validator_spec.rb
index 04cf5d0..7347b9b 100644
--- a/spec/lib/diaspora_federation/validators/message_validator_spec.rb
+++ b/spec/lib/diaspora_federation/validators/message_validator_spec.rb
@@ -3,7 +3,7 @@ module DiasporaFederation
     let(:entity) { :message_entity }
     it_behaves_like "a common validator"
 
-    it_behaves_like "a diaspora id validator" do
+    it_behaves_like "a diaspora* ID validator" do
       let(:property) { :author }
       let(:mandatory) { true }
     end
diff --git a/spec/lib/diaspora_federation/validators/participation_validator_spec.rb b/spec/lib/diaspora_federation/validators/participation_validator_spec.rb
index 29606fa..cd7cadd 100644
--- a/spec/lib/diaspora_federation/validators/participation_validator_spec.rb
+++ b/spec/lib/diaspora_federation/validators/participation_validator_spec.rb
@@ -4,7 +4,7 @@ module DiasporaFederation
 
     it_behaves_like "a common validator"
 
-    it_behaves_like "a diaspora id validator" do
+    it_behaves_like "a diaspora* ID validator" do
       let(:property) { :author }
       let(:mandatory) { true }
     end
diff --git a/spec/lib/diaspora_federation/validators/person_validator_spec.rb b/spec/lib/diaspora_federation/validators/person_validator_spec.rb
index eaa168c..e4f7726 100644
--- a/spec/lib/diaspora_federation/validators/person_validator_spec.rb
+++ b/spec/lib/diaspora_federation/validators/person_validator_spec.rb
@@ -4,7 +4,7 @@ module DiasporaFederation
 
     it_behaves_like "a common validator"
 
-    it_behaves_like "a diaspora id validator" do
+    it_behaves_like "a diaspora* ID validator" do
       let(:property) { :author }
       let(:mandatory) { true }
     end
diff --git a/spec/lib/diaspora_federation/validators/photo_validator_spec.rb b/spec/lib/diaspora_federation/validators/photo_validator_spec.rb
index a445251..1b37864 100644
--- a/spec/lib/diaspora_federation/validators/photo_validator_spec.rb
+++ b/spec/lib/diaspora_federation/validators/photo_validator_spec.rb
@@ -4,7 +4,7 @@ module DiasporaFederation
 
     it_behaves_like "a common validator"
 
-    it_behaves_like "a diaspora id validator" do
+    it_behaves_like "a diaspora* ID validator" do
       let(:property) { :author }
       let(:mandatory) { true }
     end
diff --git a/spec/lib/diaspora_federation/validators/profile_validator_spec.rb b/spec/lib/diaspora_federation/validators/profile_validator_spec.rb
index b8e80d6..55312d8 100644
--- a/spec/lib/diaspora_federation/validators/profile_validator_spec.rb
+++ b/spec/lib/diaspora_federation/validators/profile_validator_spec.rb
@@ -4,7 +4,7 @@ module DiasporaFederation
 
     it_behaves_like "a common validator"
 
-    it_behaves_like "a diaspora id validator" do
+    it_behaves_like "a diaspora* ID validator" do
       let(:property) { :author }
       let(:mandatory) { false }
     end
diff --git a/spec/lib/diaspora_federation/validators/related_entity_validator_spec.rb b/spec/lib/diaspora_federation/validators/related_entity_validator_spec.rb
index 8807a35..41216ca 100644
--- a/spec/lib/diaspora_federation/validators/related_entity_validator_spec.rb
+++ b/spec/lib/diaspora_federation/validators/related_entity_validator_spec.rb
@@ -4,7 +4,7 @@ module DiasporaFederation
 
     it_behaves_like "a common validator"
 
-    it_behaves_like "a diaspora id validator" do
+    it_behaves_like "a diaspora* ID validator" do
       let(:property) { :author }
       let(:mandatory) { true }
     end
diff --git a/spec/lib/diaspora_federation/validators/relayable_retraction_validator_spec.rb b/spec/lib/diaspora_federation/validators/relayable_retraction_validator_spec.rb
index 7313c08..3f3e300 100644
--- a/spec/lib/diaspora_federation/validators/relayable_retraction_validator_spec.rb
+++ b/spec/lib/diaspora_federation/validators/relayable_retraction_validator_spec.rb
@@ -3,7 +3,7 @@ module DiasporaFederation
     let(:entity) { :relayable_retraction_entity }
     it_behaves_like "a common validator"
 
-    it_behaves_like "a diaspora id validator" do
+    it_behaves_like "a diaspora* ID validator" do
       let(:property) { :author }
       let(:mandatory) { true }
     end
diff --git a/spec/lib/diaspora_federation/validators/request_validator_spec.rb b/spec/lib/diaspora_federation/validators/request_validator_spec.rb
index 1b0ddb8..4c40fe7 100644
--- a/spec/lib/diaspora_federation/validators/request_validator_spec.rb
+++ b/spec/lib/diaspora_federation/validators/request_validator_spec.rb
@@ -6,7 +6,7 @@ module DiasporaFederation
 
     %i(author recipient).each do |prop|
       describe "##{prop}" do
-        it_behaves_like "a diaspora id validator" do
+        it_behaves_like "a diaspora* ID validator" do
           let(:property) { prop }
           let(:mandatory) { true }
         end
diff --git a/spec/lib/diaspora_federation/validators/reshare_validator_spec.rb b/spec/lib/diaspora_federation/validators/reshare_validator_spec.rb
index 5492f12..2cc56a1 100644
--- a/spec/lib/diaspora_federation/validators/reshare_validator_spec.rb
+++ b/spec/lib/diaspora_federation/validators/reshare_validator_spec.rb
@@ -5,7 +5,7 @@ module DiasporaFederation
 
     %i(root_author author).each do |prop|
       describe "##{prop}" do
-        it_behaves_like "a diaspora id validator" do
+        it_behaves_like "a diaspora* ID validator" do
           let(:property) { prop }
           let(:mandatory) { true }
         end
diff --git a/spec/lib/diaspora_federation/validators/retraction_validator_spec.rb b/spec/lib/diaspora_federation/validators/retraction_validator_spec.rb
index 80978d1..8b92a35 100644
--- a/spec/lib/diaspora_federation/validators/retraction_validator_spec.rb
+++ b/spec/lib/diaspora_federation/validators/retraction_validator_spec.rb
@@ -7,7 +7,7 @@ module DiasporaFederation
       let(:property) { :target_guid }
     end
 
-    it_behaves_like "a diaspora id validator" do
+    it_behaves_like "a diaspora* ID validator" do
       let(:property) { :author }
       let(:mandatory) { true }
     end
diff --git a/spec/lib/diaspora_federation/validators/rules/diaspora_id_count_spec.rb b/spec/lib/diaspora_federation/validators/rules/diaspora_id_count_spec.rb
index 6f62b16..d1180b0 100644
--- a/spec/lib/diaspora_federation/validators/rules/diaspora_id_count_spec.rb
+++ b/spec/lib/diaspora_federation/validators/rules/diaspora_id_count_spec.rb
@@ -31,7 +31,7 @@ describe Validation::Rule::DiasporaIdCount do
     end
 
     it "fails for less but non ids" do
-      bad_str = "user@example.com;i am a weird diaspora id @@@ ### 12345;shouldnt be reached by a rule"
+      bad_str = "user@example.com;i am a weird diaspora* ID @@@ ### 12345;shouldnt be reached by a rule"
       validator = Validation::Validator.new(OpenStruct.new(ids: bad_str))
       validator.rule(:ids, diaspora_id_count: {maximum: 5})
 
diff --git a/spec/lib/diaspora_federation/validators/rules/diaspora_id_spec.rb b/spec/lib/diaspora_federation/validators/rules/diaspora_id_spec.rb
index b87fabe..0e9006a 100644
--- a/spec/lib/diaspora_federation/validators/rules/diaspora_id_spec.rb
+++ b/spec/lib/diaspora_federation/validators/rules/diaspora_id_spec.rb
@@ -11,7 +11,7 @@ describe Validation::Rule::DiasporaId do
   end
 
   context "validation" do
-    it "validates a normal diaspora id" do
+    it "validates a normal diaspora* ID" do
       validator = Validation::Validator.new(OpenStruct.new(diaspora_id: "some_user@example.com"))
       validator.rule(:diaspora_id, :diaspora_id)
 
@@ -19,7 +19,7 @@ describe Validation::Rule::DiasporaId do
       expect(validator.errors).to be_empty
     end
 
-    it "validates a diaspora id with localhost" do
+    it "validates a diaspora* ID with localhost" do
       validator = Validation::Validator.new(OpenStruct.new(diaspora_id: "some_user@localhost"))
       validator.rule(:diaspora_id, :diaspora_id)
 
@@ -27,7 +27,7 @@ describe Validation::Rule::DiasporaId do
       expect(validator.errors).to be_empty
     end
 
-    it "validates a diaspora id with port" do
+    it "validates a diaspora* ID with port" do
       validator = Validation::Validator.new(OpenStruct.new(diaspora_id: "some_user@example.com:3000"))
       validator.rule(:diaspora_id, :diaspora_id)
 
@@ -35,7 +35,7 @@ describe Validation::Rule::DiasporaId do
       expect(validator.errors).to be_empty
     end
 
-    it "validates a diaspora id with IPv4 address" do
+    it "validates a diaspora* ID with IPv4 address" do
       validator = Validation::Validator.new(OpenStruct.new(diaspora_id: "some_user@123.45.67.89"))
       validator.rule(:diaspora_id, :diaspora_id)
 
@@ -43,7 +43,7 @@ describe Validation::Rule::DiasporaId do
       expect(validator.errors).to be_empty
     end
 
-    it "validates a diaspora id with IPv6 address" do
+    it "validates a diaspora* ID with IPv6 address" do
       validator = Validation::Validator.new(OpenStruct.new(diaspora_id: "some_user@[2001:1234:5678:90ab:cdef::1]"))
       validator.rule(:diaspora_id, :diaspora_id)
 
@@ -51,7 +51,7 @@ describe Validation::Rule::DiasporaId do
       expect(validator.errors).to be_empty
     end
 
-    it "validates a diaspora id with . and -" do
+    it "validates a diaspora* ID with . and -" do
       validator = Validation::Validator.new(OpenStruct.new(diaspora_id: "some-fancy.user@example.com"))
       validator.rule(:diaspora_id, :diaspora_id)
 
@@ -59,7 +59,7 @@ describe Validation::Rule::DiasporaId do
       expect(validator.errors).to be_empty
     end
 
-    it "fails if the diaspora id contains a / in the domain-name" do
+    it "fails if the diaspora* ID contains a / in the domain-name" do
       validator = Validation::Validator.new(OpenStruct.new(diaspora_id: "some_user@example.com/friendica"))
       validator.rule(:diaspora_id, :diaspora_id)
 
@@ -67,7 +67,7 @@ describe Validation::Rule::DiasporaId do
       expect(validator.errors).to include(:diaspora_id)
     end
 
-    it "fails if the diaspora id contains a _ in the domain-name" do
+    it "fails if the diaspora* ID contains a _ in the domain-name" do
       validator = Validation::Validator.new(OpenStruct.new(diaspora_id: "some_user@invalid_domain.com"))
       validator.rule(:diaspora_id, :diaspora_id)
 
@@ -75,7 +75,7 @@ describe Validation::Rule::DiasporaId do
       expect(validator.errors).to include(:diaspora_id)
     end
 
-    it "fails if the diaspora id contains a special-chars in the username" do
+    it "fails if the diaspora* ID contains a special-chars in the username" do
       validator = Validation::Validator.new(OpenStruct.new(diaspora_id: "some_user$^%@example.com"))
       validator.rule(:diaspora_id, :diaspora_id)
 
diff --git a/spec/lib/diaspora_federation/validators/signed_retraction_validator_spec.rb b/spec/lib/diaspora_federation/validators/signed_retraction_validator_spec.rb
index df295c9..f304c67 100644
--- a/spec/lib/diaspora_federation/validators/signed_retraction_validator_spec.rb
+++ b/spec/lib/diaspora_federation/validators/signed_retraction_validator_spec.rb
@@ -3,7 +3,7 @@ module DiasporaFederation
     let(:entity) { :signed_retraction_entity }
     it_behaves_like "a common validator"
 
-    it_behaves_like "a diaspora id validator" do
+    it_behaves_like "a diaspora* ID validator" do
       let(:property) { :author }
       let(:mandatory) { true }
     end
diff --git a/spec/lib/diaspora_federation/validators/status_message_validator_spec.rb b/spec/lib/diaspora_federation/validators/status_message_validator_spec.rb
index e4f2cd1..9d5d360 100644
--- a/spec/lib/diaspora_federation/validators/status_message_validator_spec.rb
+++ b/spec/lib/diaspora_federation/validators/status_message_validator_spec.rb
@@ -4,7 +4,7 @@ module DiasporaFederation
 
     it_behaves_like "a common validator"
 
-    it_behaves_like "a diaspora id validator" do
+    it_behaves_like "a diaspora* ID validator" do
       let(:property) { :author }
       let(:mandatory) { true }
     end
diff --git a/spec/support/shared_validator_specs.rb b/spec/support/shared_validator_specs.rb
index aee80df..f8b2e95 100644
--- a/spec/support/shared_validator_specs.rb
+++ b/spec/support/shared_validator_specs.rb
@@ -18,7 +18,7 @@ shared_examples "a common validator" do
 end
 
 shared_examples "a relayable validator" do
-  it_behaves_like "a diaspora id validator" do
+  it_behaves_like "a diaspora* ID validator" do
     let(:property) { :author }
     let(:mandatory) { true }
   end
@@ -69,7 +69,7 @@ shared_examples "a property that mustn't be empty" do
   end
 end
 
-shared_examples "a diaspora id validator" do
+shared_examples "a diaspora* ID validator" do
   it "must not be nil or empty if mandatory" do
     [nil, ""].each do |val|
       validator = described_class.new(entity_stub(entity, property => val))
@@ -84,8 +84,8 @@ shared_examples "a diaspora id validator" do
     end
   end
 
-  it "must be a valid diaspora id" do
-    validator = described_class.new(entity_stub(entity, property => "i am a weird diaspora id @@@ ### 12345"))
+  it "must be a valid diaspora* ID" do
+    validator = described_class.new(entity_stub(entity, property => "i am a weird diaspora* ID @@@ ### 12345"))
 
     expect(validator).not_to be_valid
     expect(validator.errors).to include(property)