write more documentation

2015-06-25 04:17:14 +02:00 · 2015-06-25 04:17:14 +02:00 · 8b9aa74953
commit 8b9aa74953
parent 8eee811914
5 changed files with 76 additions and 17 deletions
--- a/README.md
+++ b/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

--- a/lib/diaspora_federation/web_finger/exceptions.rb
+++ b/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
--- a/lib/diaspora_federation/web_finger/h_card.rb
+++ b/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,
-                  :photo_full_url, :photo_medium_url, :photo_small_url
+      # 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
+
+      # 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]
          #######################################
--- a/lib/diaspora_federation/web_finger/web_finger.rb
+++ b/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)}
--- a/lib/diaspora_federation/web_finger/xrd_document.rb
+++ b/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