write more documentation

README.md

@@ -6,12 +6,12 @@
 [![Code Climate](https://codeclimate.com/github/SuperTux88/diaspora_federation/badges/gpa.svg)](https://codeclimate.com/github/SuperTux88/diaspora_federation)
 [![Test Coverage](https://codeclimate.com/github/SuperTux88/diaspora_federation/badges/coverage.svg)](https://codeclimate.com/github/SuperTux88/diaspora_federation/coverage)
 [![Dependency Status](https://gemnasium.com/SuperTux88/diaspora_federation.svg)](https://gemnasium.com/SuperTux88/diaspora_federation)
-[![Inline docs](http://inch-ci.org/github/SuperTux88/diaspora_federation.svg?branch=master)](http://inch-ci.org/github/SuperTux88/diaspora_federation)
+[![Inline docs](https://inch-ci.org/github/SuperTux88/diaspora_federation.svg?branch=master)](https://inch-ci.org/github/SuperTux88/diaspora_federation)
 
 [Documentation](http://www.rubydoc.info/github/SuperTux88/diaspora_federation/master) |
 [Project site](https://diasporafoundation.org) |
 [Wiki](https://wiki.diasporafoundation.org) |
-[Bugtracker](http://github.com/SuperTux88/diaspora_federation/issues)
+[Bugtracker](https://github.com/SuperTux88/diaspora_federation/issues)
 
 ## License
 

lib/diaspora_federation/web_finger/exceptions.rb

@@ -11,7 +11,7 @@ module DiasporaFederation
     # * if the +webfinger_url+ is missing or malformed in {HostMeta.from_base_url} or {HostMeta.from_xml}
     # * if the +data+ given to {WebFinger.from_person} is an invalid type or doesn't contain all required entries
     # * if the parsed XML from {WebFinger.from_xml} is incomplete
-    # * if the params passed to {HCard.from_account} or {HCard.from_html}
+    # * if the params passed to {HCard.from_profile} or {HCard.from_html}
     #   are in some way malformed, invalid or incomplete.
     class InvalidData < RuntimeError
     end

lib/diaspora_federation/web_finger/h_card.rb

@@ -43,17 +43,61 @@ module DiasporaFederation
     class HCard
       private_class_method :new
 
-      attr_reader :guid, :nickname, :full_name, :url, :pubkey,
+      # This is just the guid. When a user creates an account on a pod, the pod
-                  :photo_full_url, :photo_medium_url, :photo_small_url
+      # MUST assign them a guid - a random hexadecimal string of at least 8
+      # hexadecimal digits.
+      # @return [String] guid
+      attr_reader :guid
+
+      # the first part of the diaspora handle
+      # @return [String] nickname
+      attr_reader :nickname
+
+      # @return [String] display name of the user
+      attr_reader :full_name
+
+      # @deprecated should be changed to the profile url. The pod url is in
+      #   the WebFinger (see {WebFinger#seed_url}, will affect older Diaspora*
+      #   installations).
+      #
+      # @return [String] link to the pod
+      attr_reader :url
+
+      # 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
+      # DER-encoded PKCS#1 key beginning with the text
+      # "-----BEGIN PUBLIC KEY-----" and ending with "-----END PUBLIC KEY-----".
+      # @return [String] public key
+      attr_reader :pubkey
+
+      # @return [String] url to the big avatar (300x300)
+      attr_reader :photo_full_url
+      # @return [String] url to the medium avatar (100x100)
+      attr_reader :photo_medium_url
+      # @return [String] url to the small avatar (50x50)
+      attr_reader :photo_small_url
 
       # @deprecated We decided to only use one name field, these should be removed
       #   in later iterations (will affect older Diaspora* installations).
-      attr_reader :first_name, :last_name
+      #
+      # @see #full_name
+      # @return [String] first name
+      attr_reader :first_name
+
+      # @deprecated We decided to only use one name field, these should be removed
+      #   in later iterations (will affect older Diaspora* installations).
+      #
+      # @see #full_name
+      # @return [String] last name
+      attr_reader :last_name
 
       # @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*
       #   installations).
+      #
+      # flag if a user is searchable by name
+      # @return [String] searchable flag
       attr_reader :searchable
 
       # CSS selectors for finding all the hCard fields
@@ -84,7 +128,7 @@ module DiasporaFederation
         add_simple_property(content, :searchable, "searchable", @searchable)
         add_simple_property(content, :key, "key", @pubkey)
 
-        # TODO: change me!  ###################
+        # TODO: remove me!  ###################
         add_simple_property(content, :first_name, "given_name", @first_name)
         add_simple_property(content, :family_name, "family_name", @last_name)
         #######################################
@@ -117,7 +161,7 @@ module DiasporaFederation
           @pubkey           = data[:pubkey]
           @searchable       = data[:searchable]
 
-          # TODO: change me!  ###################
+          # TODO: remove me!  ###################
           @first_name       = data[:first_name]
           @last_name        = data[:last_name]
           #######################################

lib/diaspora_federation/web_finger/web_finger.rb

@@ -39,15 +39,16 @@ module DiasporaFederation
 
       # The Subject element should contain the webfinger address that was asked
       # for. If it does not, then this webfinger profile MUST be ignored.
+      # @return [String]
       attr_reader :acct_uri
 
-      # Link to the users profile
+      # @return [String] link to the users profile
       attr_reader :alias_url, :profile_url
 
-      # Link to the +hCard+
+      # @return [String] link to the +hCard+
       attr_reader :hcard_url
 
-      # Link to the pod
+      # @return [String] link to the pod
       attr_reader :seed_url
 
       # This atom feed is an Activity Stream of the user's public posts. Diaspora
@@ -57,9 +58,10 @@ module DiasporaFederation
       #
       # Note that this feed MAY also be made available through the PubSubHubbub
       # mechanism by supplying a <link rel="hub"> in the atom feed itself.
+      # @return [String] atom feed url
       attr_reader :atom_url
 
-      # The salmon endpoint URL
+      # @return [String] salmon endpoint url
       # @see http://salmon-protocol.googlecode.com/svn/trunk/draft-panzer-salmon-00.html#SMLR
       #   Panzer draft for Salmon, paragraph 3.3
       attr_reader :salmon_url
@@ -68,19 +70,25 @@ module DiasporaFederation
       #   +hCard+, which actually has fields for an +UID+ defined in the +vCard+
       #   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.
+      # @return [String] guid
       attr_reader :guid
 
       # @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).
       #
+      # @see HCard#pubkey
+      #
       # 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
       # DER-encoded PKCS#1 key beginning with the text
       # "-----BEGIN PUBLIC KEY-----" and ending with "-----END PUBLIC KEY-----".
+      # @return [String] public key
       attr_reader :pubkey
 
       # +hcard_url+ link relation
@@ -140,7 +148,7 @@ module DiasporaFederation
           @atom_url    = data[:atom_url]
           @salmon_url  = data[:salmon_url]
 
-          # TODO: change me!  #########
+          # TODO: remove me!  #########
           @guid        = data[:guid]
           @pubkey      = data[:pubkey]
           #############################
@@ -167,7 +175,7 @@ module DiasporaFederation
           @atom_url    = atom_url
           @salmon_url  = salmon_url
 
-          # TODO: change me!  ##########
+          # TODO: remove me!  ##########
           @guid        = guid
           @pubkey      = Base64.strict_decode64(pubkey)
           ##############################
@@ -210,7 +218,7 @@ module DiasporaFederation
                       type: "text/html",
                       href: @seed_url}
 
-        # TODO: change me!  ##############
+        # TODO: remove me!  ##############
         doc.links << {rel:  REL_GUID,
                       type: "text/html",
                       href: @guid}
@@ -225,7 +233,7 @@ module DiasporaFederation
         doc.links << {rel:  REL_SALMON,
                       href: @salmon_url}
 
-        # TODO: change me!  ##############
+        # TODO: remove me!  ##############
         doc.links << {rel:  REL_PUBKEY,
                       type: "RSA",
                       href: Base64.strict_encode64(@pubkey)}

lib/diaspora_federation/web_finger/xrd_document.rb

@@ -38,7 +38,14 @@ module DiasporaFederation
       # format string for datetime (+Expires+ element)
       DATETIME_FORMAT = "%Y-%m-%dT%H:%M:%SZ"
 
-      attr_writer :expires, :subject
+      # The <Expires> element contains a time value which specifies the instant at
+      # and after which the document has expired and SHOULD NOT be used.
+      # @param [DateTime] value
+      attr_writer :expires
+      # The <Subject> element contains a URI value which identifies the resource
+      # described by this XRD.
+      # @param [String] value
+      attr_writer :subject
 
       # @return [Array<String>] list of alias URIs
       attr_reader :aliases