improve documentation for entities

lib/diaspora_federation/discovery/h_card.rb

@@ -41,14 +41,13 @@ module DiasporaFederation
     # @see http://www.ietf.org/rfc/rfc6350.txt "vCard Format Specification"
     class HCard < Entity
       # @!attribute [r] guid
-      #   This is just the guid. When a user creates an account on a pod, the pod
-      #   MUST assign them a guid - a random hexadecimal string of at least 8
-      #   hexadecimal digits.
+      #   @see Entities::Person#guid
       #   @return [String] guid
       property :guid
 
       # @!attribute [r] nickname
       #   the first part of the diaspora ID
+      #   @see Entities::Person#diaspora_id
       #   @return [String] nickname
       property :nickname
 

lib/diaspora_federation/discovery/web_finger.rb

@@ -81,10 +81,7 @@ module DiasporaFederation
       #     specification (will affect older Diaspora* installations).
       #
       #   @see HCard#guid
-      #
-      #   This is just the guid. When a user creates an account on a pod, the pod
-      #   MUST assign them a guid - a random hexadecimal string of at least 8
-      #   hexadecimal digits.
+      #   @see Entities::Person#guid
       #   @return [String] guid
       property :guid
 
@@ -93,7 +90,7 @@ module DiasporaFederation
       #     +hCard+, which actually has fields for an +KEY+ defined in the +vCard+
       #     specification (will affect older Diaspora* installations).
       #
-      #   @see HCard#pubkey
+      #   @see HCard#public_key
       #
       #   When a user is created on the pod, the pod MUST generate a pgp keypair
       #   for them. This key is used for signing messages. The format is a

lib/diaspora_federation/entities/comment.rb

@@ -5,8 +5,9 @@ module DiasporaFederation
     # @see Validators::CommentValidator
     class Comment < Entity
       # @!attribute [r] guid
-      #   @see HCard#guid
-      #   @return [String] guid
+      #   a random string of at least 16 chars.
+      #   @see Validation::Rule::Guid
+      #   @return [String] comment guid
       property :guid
 
       include Relayable
@@ -16,7 +17,7 @@ module DiasporaFederation
       property :text
 
       # @!attribute [r] diaspora_id
-      #   The diaspora ID of the person
+      #   The diaspora ID of the author.
       #   @see Person#diaspora_id
       #   @return [String] diaspora ID
       property :diaspora_id, xml_name: :diaspora_handle

lib/diaspora_federation/entities/conversation.rb

@@ -2,11 +2,12 @@ module DiasporaFederation
   module Entities
     # this entity represents a private conversation between users
     #
-    # @see Validators::ConverstaionValidator
+    # @see Validators::ConversationValidator
     class Conversation < Entity
       # @!attribute [r] guid
-      #   @see HCard#guid
-      #   @return [String] guid
+      #   a random string of at least 16 chars.
+      #   @see Validation::Rule::Guid
+      #   @return [String] conversation guid
       property :guid
 
       # @!attribute [r] subject
@@ -17,14 +18,20 @@ module DiasporaFederation
       #   @return [Time] Conversation creation time
       property :created_at, default: -> { Time.now.utc }
 
+      # @!attribute [r] messages
+      #   @return [[Entities::Message]] Messages of this conversation
       entity :messages, [Entities::Message]
 
       # @!attribute [r] diaspora_id
-      #   The diaspora ID of the person initiated the conversation
+      #   The diaspora ID of the person initiated the conversation.
       #   @see Person#diaspora_id
       #   @return [String] diaspora ID
       property :diaspora_id, xml_name: :diaspora_handle
 
+      # @!attribute [r] participant_ids
+      #   The diaspora IDs of the persons participating the conversation separated by ";".
+      #   @see Person#diaspora_id
+      #   @return [String] participants diaspora IDs
       property :participant_ids, xml_name: :participant_handles
     end
   end

lib/diaspora_federation/entities/like.rb

@@ -5,18 +5,21 @@ module DiasporaFederation
     # @see Validators::LikeValidator
     class Like < Entity
       # @!attribute [r] positive
-      #   If true set a like, if false, set a dislike (dislikes are currently not
-      #   implemented in the Diaspora's frontend).
+      #   If +true+ set a like, if +false+, set a dislike (dislikes are currently not
+      #   implemented in the Diaspora frontend).
       #   @return [Boolean] is it a like or a dislike
       property :positive
 
       # @!attribute [r] guid
-      #   @see HCard#guid
-      #   @return [String] guid
+      #   a random string of at least 16 chars.
+      #   @see Validation::Rule::Guid
+      #   @return [String] like guid
       property :guid
 
       # @!attribute [r] target_type
-      #   a string describing a type of the target
+      #   A string describing the type of the target.
+      #   Can be "Post" or "Comment" (Comments are currently not implemented in the
+      #   Diaspora Frontend).
       #   @return [String] target type
       property :target_type
 

lib/diaspora_federation/entities/message.rb

@@ -5,8 +5,9 @@ module DiasporaFederation
     # @see Validators::MessageValidator
     class Message < Entity
       # @!attribute [r] guid
-      #   @see HCard#guid
-      #   @return [String] guid
+      #   a random string of at least 16 chars.
+      #   @see Validation::Rule::Guid
+      #   @return [String] message guid
       property :guid
 
       include Relayable
@@ -22,14 +23,14 @@ module DiasporaFederation
       property :created_at, default: -> { Time.now.utc }
 
       # @!attribute [r] diaspora_id
-      #   The diaspora ID of the message author
+      #   The diaspora ID of the message author.
       #   @see Person#diaspora_id
       #   @return [String] diaspora ID
       property :diaspora_id, xml_name: :diaspora_handle
 
       # @!attribute [r] conversation_guid
       #   guid of a conversation this message belongs to
-      #   @see HCard#guid
+      #   @see Conversation#guid
       #   @return [String] conversation guid
       property :conversation_guid
     end

lib/diaspora_federation/entities/participation.rb

@@ -5,12 +5,14 @@ module DiasporaFederation
     # @see Validators::Participation
     class Participation < Entity
       # @!attribute [r] guid
-      #   @see HCard#guid
-      #   @return [String] guid
+      #   a random string of at least 16 chars.
+      #   @see Validation::Rule::Guid
+      #   @return [String] participation guid
       property :guid
 
       # @!attribute [r] target_type
-      #   a string describing a type of the target to subscribe on
+      #   a string describing a type of the target to subscribe on.
+      #   currently only "Post" is supported.
       #   @return [String] target type
       property :target_type
 

lib/diaspora_federation/entities/person.rb

@@ -5,17 +5,20 @@ module DiasporaFederation
     # @see Validators::PersonValidator
     class Person < Entity
       # @!attribute [r] guid
-      #   @see HCard#guid
+      #   This is just the guid. When a user creates an account on a pod, the pod
+      #   MUST assign them a guid - a random string of at least 16 chars.
+      #   @see Validation::Rule::Guid
       #   @return [String] guid
       property :guid
 
       # @!attribute [r] diaspora_id
       #   The diaspora ID of the person
+      #   @see Validation::Rule::DiasporaId
       #   @return [String] diaspora ID
       property :diaspora_id, xml_name: :diaspora_handle
 
       # @!attribute [r] url
-      #   @see WebFinger#seed_url
+      #   @see Discovery::WebFinger#seed_url
       #   @return [String] link to the pod
       property :url
 
@@ -25,7 +28,7 @@ module DiasporaFederation
       entity :profile, Entities::Profile
 
       # @!attribute [r] exported_key
-      #   @see HCard#public_key
+      #   @see Discovery::HCard#public_key
       #   @return [String] public key
       property :exported_key
     end

lib/diaspora_federation/entities/photo.rb

@@ -5,14 +5,15 @@ module DiasporaFederation
     # @see Validators::PhotoValidator
     class Photo < Entity
       # @!attribute [r] guid
-      #   @see HCard#guid
+      #   a random string of at least 16 chars.
+      #   @see Validation::Rule::Guid
       #   @return [String] guid
       property :guid
 
       # @!attribute [r] diaspora_id
       #   The diaspora ID of the person who uploaded the photo
       #   @see Person#diaspora_id
-      #   @return [String] diaspora ID
+      #   @return [String] author diaspora ID
       property :diaspora_id, xml_name: :diaspora_handle
 
       # @!attribute [r] public
@@ -40,7 +41,7 @@ module DiasporaFederation
 
       # @!attribute [r] status_message_guid
       #   guid of a status message this message belongs to
-      #   @see HCard#guid
+      #   @see StatusMessage#guid
       #   @return [String] guid
       property :status_message_guid
 

lib/diaspora_federation/entities/poll.rb

@@ -5,8 +5,9 @@ module DiasporaFederation
     # @see Validators::PollValidator
     class Poll < Entity
       # @!attribute [r] guid
-      #   @see HCard#guid
-      #   @return [String] guid
+      #   a random string of at least 16 chars.
+      #   @see Validation::Rule::Guid
+      #   @return [String] poll guid
       property :guid
 
       # @!attribute [r] question

lib/diaspora_federation/entities/poll_answer.rb

@@ -5,7 +5,8 @@ module DiasporaFederation
     # @see Validators::PollAnswerValidator
     class PollAnswer < Entity
       # @!attribute [r] guid
-      #   @see HCard#guid
+      #   a random string of at least 16 chars.
+      #   @see Validation::Rule::Guid
       #   @return [String] guid
       property :guid
 

lib/diaspora_federation/entities/poll_participation.rb

@@ -5,7 +5,8 @@ module DiasporaFederation
     # @see Validators::PollParticipationValidator
     class PollParticipation < Entity
       # @!attribute [r] guid
-      #   @see HCard#guid
+      #   a random string of at least 16 chars.
+      #   @see Validation::Rule::Guid
       #   @return [String] guid
       property :guid
 
@@ -18,8 +19,8 @@ module DiasporaFederation
       property :diaspora_id, xml_name: :diaspora_handle
 
       # @!attribute [r] poll_answer_guid
-      #   guid of the answer selected by user
-      #   @see HCard#guid
+      #   guid of the answer selected by the user.
+      #   @see PollAnswer#guid
       #   @return [String] poll answer guid
       property :poll_answer_guid
     end

lib/diaspora_federation/entities/profile.rb

@@ -11,29 +11,31 @@ module DiasporaFederation
       property :diaspora_id, xml_name: :diaspora_handle
 
       # @!attribute [r] first_name
-      #   @deprecated
+      #   @deprecated We decided to only use one name field, these should be removed
+      #     in later iterations (will affect older Diaspora* installations).
       #   @see #full_name
-      #   @see HCard#first_name
+      #   @see Discovery::HCard#first_name
       #   @return [String] first name
       property :first_name, default: nil
 
       # @!attribute [r] last_name
-      #   @deprecated
+      #   @deprecated We decided to only use one name field, these should be removed
+      #     in later iterations (will affect older Diaspora* installations).
       #   @see #full_name
-      #   @see HCard#last_name
+      #   @see Discovery::HCard#last_name
       #   @return [String] last name
       property :last_name, default: nil
 
       # @!attribute [r] image_url
-      #   @see HCard#photo_large_url
+      #   @see Discovery::HCard#photo_large_url
       #   @return [String] url to the big avatar (300x300)
       property :image_url, default: nil
       # @!attribute [r] image_url_medium
-      #   @see HCard#photo_medium_url
+      #   @see Discovery::HCard#photo_medium_url
       #   @return [String] url to the medium avatar (100x100)
       property :image_url_medium, default: nil
       # @!attribute [r] image_url_small
-      #   @see HCard#photo_small_url
+      #   @see Discovery::HCard#photo_small_url
       #   @return [String] url to the small avatar (50x50)
       property :image_url_small, default: nil
 
@@ -43,7 +45,7 @@ module DiasporaFederation
       property :location, default: nil
 
       # @!attribute [r] searchable
-      #   @see HCard#searchable
+      #   @see Discovery::HCard#searchable
       #   @return [Boolean] searchable flag
       property :searchable, default: true
 

lib/diaspora_federation/entities/relayable.rb

@@ -6,27 +6,30 @@ module DiasporaFederation
     # logic is embedded into Salmon XML processing code.
     module Relayable
       # on inclusion of this module the required properties for a relayable are added to the object that includes it
-      def self.included(model)
-        model.class_eval do
-          # @!attribute [r] parent_guid
-          #   @see HCard#guid
-          #   @return [String] parent guid
+      #
+      # @!attribute [r] parent_guid
+      #   @see StatusMessage#guid
+      #   @return [String] parent guid
+      #
+      # @!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
+      #   downstream subscribers. This is the case when the parent author has to resend a relayable
+      #   received from one of his subscribers to all others.
+      #
+      #   @return [String] parent author signature
+      #
+      # @!attribute [r] author_signature
+      #   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
+      #
+      # @param [Entity] entity the entity in which it is included
+      def self.included(entity)
+        entity.class_eval do
           property :parent_guid
-
-          # @!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
-          #   downstream subscribers. This is the case when the parent author has to resend a relayable
-          #   received from one of his subscribers to all others.
-          #
-          #   @return [String] parent author signature
           property :parent_author_signature, default: nil
-
-          # @!attribute [r] author_signature
-          #   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
           property :author_signature, default: nil
         end
       end

lib/diaspora_federation/entities/relayable_retraction.rb

@@ -22,21 +22,24 @@ module DiasporaFederation
       # @!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.
+      #   @see Relayable#parent_author_signature
       #   @return [String] parent author signature
       property :parent_author_signature, default: nil
 
       # @!attribute [r] target_guid
-      #   guid of a post to be deleted
-      #   @see HCard#guid
+      #   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
+      #   @see Retraction#target_type
       #   @return [String] target type
       property :target_type
 
       # @!attribute [r] diaspora_id
-      #   The diaspora ID of the person who deletes a post
+      #   The diaspora ID of the person who deletes a relayable
       #   @see Person#diaspora_id
       #   @return [String] diaspora ID
       property :diaspora_id, xml_name: :sender_handle
@@ -46,6 +49,7 @@ module DiasporaFederation
       #   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
       #   @return [String] target author signature
       property :target_author_signature, default: nil
 

lib/diaspora_federation/entities/request.rb

@@ -1,12 +1,12 @@
 module DiasporaFederation
   module Entities
     # this entity represents a sharing request for a user. A user issues it
-    # when she wants to share her private posts with the recipient.
+    # when he starts sharing with another user.
     #
     # @see Validators::RequestValidator
     class Request < Entity
       # @!attribute [r] sender_id
-      #   The diaspora ID of the person who shares his private posts
+      #   The diaspora ID of the person who shares his profile
       #   @see Person#diaspora_id
       #   @return [String] sender ID
       property :sender_id, xml_name: :sender_handle

lib/diaspora_federation/entities/reshare.rb

@@ -12,12 +12,14 @@ module DiasporaFederation
 
       # @!attribute [r] root_guid
       #   guid of the original post
-      #   @see HCard#guid
+      #   @see StatusMessage#guid
       #   @return [String] root guid
       property :root_guid
 
       # @!attribute [r] guid
-      #   @see HCard#guid
+      #   a random string of at least 16 chars.
+      #   @see Validation::Rule::Guid
+      #   @see StatusMessage#guid
       #   @return [String] guid
       property :guid
 
@@ -39,6 +41,7 @@ module DiasporaFederation
 
       # @!attribute [r] provider_display_name
       #   a string that describes a means by which a user has posted the reshare
+      #   @see StatusMessage#provider_display_name
       #   @return [String] provider display name
       property :provider_display_name, default: nil
     end

lib/diaspora_federation/entities/retraction.rb

@@ -1,23 +1,22 @@
 module DiasporaFederation
   module Entities
     # this entity represents a claim of deletion of a previously federated
-    # entity that is not a post or a relayable (now it includes only {Entities::Photo})
     #
     # @see Validators::RetractionValidator
     class Retraction < Entity
       # @!attribute [r] target_guid
       #   guid of the entity to be deleted
-      #   @see HCard#guid
       #   @return [String] target guid
       property :target_guid, xml_name: :post_guid
 
       # @!attribute [r] diaspora_id
-      #   The diaspora ID of the person who deletes a post
+      #   The diaspora ID of the person who deletes the entity
       #   @see Person#diaspora_id
       #   @return [String] diaspora ID
       property :diaspora_id, xml_name: :diaspora_handle
 
       # @!attribute [r] target_type
+      #   A string describing the type of the target.
       #   @return [String] target type
       property :target_type, xml_name: :type
     end

lib/diaspora_federation/entities/signed_retraction.rb

@@ -8,11 +8,13 @@ module DiasporaFederation
     class SignedRetraction < Entity
       # @!attribute [r] target_guid
       #   guid of a post to be deleted
-      #   @see HCard#guid
+      #   @see Retraction#target_guid
       #   @return [String] target guid
       property :target_guid
 
       # @!attribute [r] target_type
+      #   A string describing the type of the target.
+      #   @see Retraction#target_type
       #   @return [String] target type
       property :target_type
 
@@ -55,7 +57,7 @@ module DiasporaFederation
       # a signature since it is included from signable_string for SignedRetraction and RelayableRetraction
       #
       # @param [Hash] data hash of the retraction properties
-      # @retrun [Hash] hash copy without :diaspora_id member
+      # @return [Hash] hash copy without :diaspora_id member
       def self.apply_signable_exceptions(data)
         data.dup.tap {|data| data.delete(:diaspora_id) }
       end

lib/diaspora_federation/entities/status_message.rb

@@ -5,7 +5,7 @@ module DiasporaFederation
     # @see Validators::StatusMessageValidator
     class StatusMessage < Entity
       # @!attribute [r] raw_message
-      #   text of the status message composed by a user
+      #   text of the status message composed by the user
       #   @return [String] text of the status message
       property :raw_message
 
@@ -25,8 +25,9 @@ module DiasporaFederation
       entity :poll, Entities::Poll, default: nil
 
       # @!attribute [r] guid
-      #   @see HCard#guid
-      #   @return [String] guid
+      #   a random string of at least 16 chars.
+      #   @see Validation::Rule::Guid
+      #   @return [String] status message guid
       property :guid
 
       # @!attribute [r] diaspora_id
@@ -36,7 +37,7 @@ module DiasporaFederation
       property :diaspora_id, xml_name: :diaspora_handle
 
       # @!attribute [r] public
-      #   Points if 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