From 8b9aa7495337ff0ab7408bde0f3a56c35cc6c01d Mon Sep 17 00:00:00 2001 From: Benjamin Neff Date: Thu, 25 Jun 2015 04:17:14 +0200 Subject: [PATCH] write more documentation --- README.md | 4 +- .../web_finger/exceptions.rb | 2 +- lib/diaspora_federation/web_finger/h_card.rb | 54 +++++++++++++++++-- .../web_finger/web_finger.rb | 24 ++++++--- .../web_finger/xrd_document.rb | 9 +++- 5 files changed, 76 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index e96d875..abac1df 100644 --- 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 diff --git a/lib/diaspora_federation/web_finger/exceptions.rb b/lib/diaspora_federation/web_finger/exceptions.rb index f61f5c0..795ad2c 100644 --- 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 diff --git a/lib/diaspora_federation/web_finger/h_card.rb b/lib/diaspora_federation/web_finger/h_card.rb index 6015c40..a0e1f4d 100644 --- 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] ####################################### diff --git a/lib/diaspora_federation/web_finger/web_finger.rb b/lib/diaspora_federation/web_finger/web_finger.rb index c28b221..6ae24c8 100644 --- 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 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)} diff --git a/lib/diaspora_federation/web_finger/xrd_document.rb b/lib/diaspora_federation/web_finger/xrd_document.rb index 0706ebd..8d3dbc2 100644 --- 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 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 element contains a URI value which identifies the resource + # described by this XRD. + # @param [String] value + attr_writer :subject # @return [Array] list of alias URIs attr_reader :aliases