From 7702513ca5b94f33e73d31ae9662a9158fe3d890 Mon Sep 17 00:00:00 2001
From: cmrd Senya <senya@riseup.net>
Date: Wed, 9 Dec 2015 18:57:45 +0300
Subject: [PATCH] Documentation for the callbacks

---
 lib/diaspora_federation.rb | 57 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)

diff --git a/lib/diaspora_federation.rb b/lib/diaspora_federation.rb
index 420bc4d..3ec9417 100644
--- a/lib/diaspora_federation.rb
+++ b/lib/diaspora_federation.rb
@@ -66,6 +66,63 @@ module DiasporaFederation
 
     # 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
+    # application or posting data to the application.
+    #
+    # Callbacks are implemented at the application side and must follow these specifications:
+    #
+    # fetch_person_for_webfinger
+    #   Fetches person data from the application to form a WebFinger reply
+    #   @param [String] Diaspora ID of the person
+    #   @return [DiasporaFederation::Discovery::WebFinger] person webfinger data
+    #
+    # fetch_person_for_hcard
+    #   Fetches person data from the application to reply for an HCard query
+    #   @param [String] guid of the person
+    #   @return [DiasporaFederation::Discovery::HCard] person hcard data
+    #
+    # save_person_after_webfinger
+    #   After the gem had made a person discovery using WebFinger it calls this callback
+    #   so the application saves the person data
+    #   @param [DiasporaFederation::Entities::Person] person data
+    #
+    # fetch_private_key_by_diaspora_id
+    #   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_author_private_key_by_entity_guid
+    #   Fetches a private key of the person who authored an entity identified by a given guid
+    #   @param [String] entity type (Post, Comment, Like, etc)
+    #   @param [String] guid of the entity
+    #   @return [OpenSSL::PKey::RSA] key
+    #
+    # fetch_public_key_by_diaspora_id
+    #   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_author_public_key_by_entity_guid
+    #   Fetches a public key of the person who authored an entity identified by a given guid
+    #   @param [String] entity type (Post, Comment, Like, etc)
+    #   @param [String] guid of the entity
+    #   @return [OpenSSL::PKey::RSA] key
+    #
+    # entity_author_is_local?
+    #   Reports if the author of the entity identified by a given guid is local on the pod
+    #   where we operate.
+    #   @param [String] entity type (Post, Comment, Like, etc)
+    #   @param [String] guid of the entity
+    #   @return [Boolean]
+    #
+    # fetch_entity_author_id_by_guid
+    #   Fetches Diaspora ID of the person who authored the entity identified by a given guid
+    #   @param [String] entity type (Post, Comment, Like, etc)
+    #   @param [String] guid of the entity
+    #   @return [String] Diaspora ID of the person
+    #
+    #
     # @example
     #   config.define_callbacks do
     #     on :some_event do |arg1|