extra Documentation (#24)

* update documentation

* more comments

* Update lib/passkit/factory.rb

Co-authored-by: Alessandro Rodi <[email protected]>

* Update lib/passkit/base_pass.rb

Co-authored-by: Alessandro Rodi <[email protected]>

---------

Co-authored-by: Alessandro Rodi <[email protected]>

Author: annaswims

README.md

@@ -128,9 +128,14 @@ You can define colors, fields and texts. You can also define the logo and the ba
 You should place the images in a 'private/passkit/<your_downcased_passname>' folder.
 There is a [dummy app in the gem](test/dummy) that you can use to check how to create your own Wallet Passes.
 
+Full documentation for image specifications is on Apple's
+[Pass Design and Creation](https://developer.apple.com/library/archive/documentation/UserExperience/Conceptual/PassKit_PG/Creating.html)
+page. Naming the file according to convetion and putting it in 'private/passkit/<your_downcased_passname>' is all that's needed for it
+to be included in the pass.
+
 ### Serve your Wallet Pass
 
-Use the [Passkit::UrlGenerator](lib/passkit/url_generator.rb) to generate the URL to serve your Wallet Pass. 
+Use the [Passkit::UrlGenerator](lib/passkit/url_generator.rb) to generate the URL to serve your Wallet Pass.
 You can initialize it with:
 
 ```ruby

docs/passkit_environment_variables.md

@@ -12,7 +12,7 @@ In production, it will simply be your domain name, but in development you can us
 
 This is the easy one.
 Head to https://www.apple.com/certificateauthority/ and download the latest Apple Intermediate Certificate Worldwide Developer Relations.
-You might want to choose the one with the longest expiration date.
+You might want to choose the one with the longest expiration date. PASSKIT_APPLE_INTERMEDIATE_CERTIFICATE is the path to the certificate.
 
 ### `PASSKIT_APPLE_TEAM_IDENTIFIER`
 
@@ -32,7 +32,7 @@ Head to your Apple Developers console and generate a new certificate.
 
 The identifier is the `PASSKIT_PASS_TYPE_IDENTIFIER` variable.
 
-Now, create a certificate signing request: https://help.apple.com/developer-account/#/devbfa00fef7
+Now, create a certificate signing request: https://developer.apple.com/help/account/create-certificates/create-a-certificate-signing-request/
 
 And create the certificate:
 

lib/passkit/base_pass.rb

@@ -47,30 +47,40 @@ def web_service_url
       "#{ENV["PASSKIT_WEB_SERVICE_HOST"]}/passkit/api"
     end
 
+    # The foreground color, used for the values of fields shown on the front of the pass.
     def foreground_color
       # black
       "rgb(0, 0, 0)"
     end
 
+    # The background color, used for the background of the front and back of the pass.
+    # If you provide a background image, any background color is ignored.
     def background_color
       # white
       "rgb(255, 255, 255)"
     end
 
+    # The label color, used for the labels of fields shown on the front of the pass.
     def label_color
       # black
       "rgb(0, 0, 0)"
     end
 
+    # The organization name is displayed on the lock screen when your pass is relevant and by apps such as Mail which
+    # act as a conduit for passes. The value for the organizationName key in the pass specifies the organization name.
+    # Choose a name that users recognize and associate with your organization or company.
     def organization_name
       "Passkit"
     end
 
+    # The description lets VoiceOver make your pass accessible to blind and low-vision users. The value for the
+    # description key in the pass specifies the description.
+    # @see https://developer.apple.com/library/archive/documentation/UserExperience/Conceptual/PassKit_PG/Creating.html
     def description
       "A basic description for a pass"
     end
 
-    # A pass can have up to ten relevant locations
+    # An array of up to 10 latitudes and longitudes. iOS uses these locations to determine when to display the pass on the lock screen
     #
     # @see https://developer.apple.com/library/archive/documentation/UserExperience/Conceptual/PassKit_PG/Creating.html
     def locations
@@ -133,7 +143,7 @@ def event_ticket
 
     # Date and time the pass expires, must include
     # days, hours and minutes (seconds are optional)
-    # Returns a String representing the date and time in W3C format
+    # Returns a String representing the date and time in W3C format ("%Y-%m-%dT%H:%M:%S%z")
     def expiration_date
     end
 
@@ -157,7 +167,7 @@ def nfc
     # Date and time when the pass becomes relevant and should be
     # displayed, must include days, hours and minutes
     # (seconds are optional)
-    # Returns a String representing the date and time in W3C format
+    # Returns a String representing the date and time in W3C format ("%Y-%m-%dT%H:%M:%S%z")
     def relevant_date
     end
 

lib/passkit/factory.rb

@@ -1,6 +1,7 @@
 module Passkit
   class Factory
     class << self
+      # generator is an optional ActiveRecord object, the application data for the pass
       def create_pass(pass_class, generator = nil)
         pass = Passkit::Pass.create!(klass: pass_class, generator: generator)
         Passkit::Generator.new(pass).generate_and_sign