add more docs

src/awscr-s3.cr

@@ -4,5 +4,6 @@ require "./awscr-s3/*"
 
 # AWS S3 access via Crystal.
 module Awscr::S3
+  # :nodoc:
   SERVICE_NAME = "s3"
 end

src/awscr-s3/bucket.cr

@@ -1,6 +1,13 @@
 module Awscr::S3
   class Bucket
-    getter name, creation_time, owner
+    # The name of the bucket
+    getter name
+
+    # The time the bucket was created
+    getter creation_time
+
+    # The owner of the bucket
+    getter owner
 
     # An S3 Bucket
     def initialize(@name : String, @creation_time : Time, @owner : String? = nil)

src/awscr-s3/client.cr

@@ -38,7 +38,7 @@ module Awscr::S3
     # List s3 buckets
     #
     # ```
-    # client = Client.new("region", "key", "secret", signer: :v2)
+    # client = Client.new("region", "key", "secret")
     # resp = client.list_buckets
     # p resp.buckets.map(&.name) # => ["bucket1", "bucket2"]
     # ```
@@ -87,7 +87,7 @@ module Awscr::S3
     # Start a multipart upload
     #
     # ```
-    # client = Client.new("region", "key", "secret", signer: :v2)
+    # client = Client.new("region", "key", "secret")
     # resp = client.start_multipart_upload("bucket1", "obj")
     # p resp.upload_id # => someid
     # ```
@@ -101,7 +101,7 @@ module Awscr::S3
     # Upload a part, for use in multipart uploading
     #
     # ```
-    # client = Client.new("region", "key", "secret", signer: :v2)
+    # client = Client.new("region", "key", "secret")
     # resp = client.upload_part("bucket1", "obj", "someid", 123, "MY DATA")
     # p resp.upload_id # => someid
     # ```
@@ -119,7 +119,7 @@ module Awscr::S3
     # Complete a multipart upload
     #
     # ```
-    # client = Client.new("region", "key", "secret", signer: :v2)
+    # client = Client.new("region", "key", "secret")
     # resp = client.complete_multipart_upload("bucket1", "obj", "123", parts)
     # p resp.key # => obj
     # ```
@@ -148,7 +148,7 @@ module Awscr::S3
     # otherwise.
     #
     # ```
-    # client = Client.new("region", "key", "secret", signer: :v2)
+    # client = Client.new("region", "key", "secret")
     # resp = client.abort_multipart_upload("bucket1", "obj", "123")
     # p resp # => true
     # ```
@@ -162,7 +162,7 @@ module Awscr::S3
     # Raises a `Http::ServerError` if the bucket does not exist.
     #
     # ```
-    # client = Client.new("region", "key", "secret", signer: :v2)
+    # client = Client.new("region", "key", "secret")
     # resp = client.head_bucket("bucket1")
     # p resp # => true
     # ```
@@ -176,7 +176,7 @@ module Awscr::S3
     # otherwise.
     #
     # ```
-    # client = Client.new("region", "key", "secret", signer: :v2)
+    # client = Client.new("region", "key", "secret")
     # resp = client.delete_object("bucket1", "obj")
     # p resp # => true
     # ```
@@ -194,7 +194,7 @@ module Awscr::S3
     # and use that as return object
     #
     # ```
-    # client = Client.new("region", "key", "secret", signer: :v2)
+    # client = Client.new("region", "key", "secret")
     # resp = client.batch_delete("bucket1", ["obj", "obj2"])
     # p resp # => true
     # ```
@@ -227,7 +227,7 @@ module Awscr::S3
     # Add an object to a bucket.
     #
     # ```
-    # client = Client.new("region", "key", "secret", signer: :v2)
+    # client = Client.new("region", "key", "secret")
     # resp = client.put_object("bucket1", "obj", "MY DATA")
     # p resp.key # => "obj"
     # ```
@@ -241,7 +241,7 @@ module Awscr::S3
     # Get the contents of an object in a bucket
     #
     # ```
-    # client = Client.new("region", "key", "secret", signer: :v2)
+    # client = Client.new("region", "key", "secret")
     # resp = client.get_object("bucket1", "obj")
     # p resp.body # => "MY DATA"
     # ```
@@ -254,7 +254,7 @@ module Awscr::S3
     # List all the items in a bucket
     #
     # ```
-    # client = Client.new("region", "key", "secret", signer: :v2)
+    # client = Client.new("region", "key", "secret")
     # resp = client.list_objects("bucket1", prefix: "test")
     # p resp.map(&.key) # => ["obj"]
     # ```

src/awscr-s3/content_type.cr

@@ -1,8 +1,10 @@
 module Awscr::S3
   # Determines the Content-Type of IO
   class ContentType
+    # The default content type if one can not be determined from the filename
     DEFAULT = "binary/octet-stream"
 
+    # :nodoc:
     TYPES = {
       ".aac"   => "audio/aac",
       ".abw"   => "application/x-abiword",
@@ -72,6 +74,8 @@ module Awscr::S3
       ".7z"    => "application/x-7z-compressed",
     }
 
+    # Gets a content type based on the file extesion, if there is no file
+    # extension it uses the default content type
     def self.get(io : IO) : String
       case io
       when .responds_to?(:path)

src/awscr-s3/file_uploader.cr

@@ -9,7 +9,8 @@ module Awscr::S3
 
     # Configurable options passed to a FileUploader instance
     struct Options
-      property with_content_types
+      # If true the uploader will automatically add a content type header
+      getter with_content_types
 
       def initialize(@with_content_types : Bool)
       end

src/awscr-s3/http.cr

@@ -7,6 +7,7 @@ module Awscr::S3
     # Exception raised when S3 gives us a non 200 http status code. The error
     # will have a specific message from S3.
     class ServerError < Exception
+      # Creates a `ServerError` from an `HTTP::Client::Response`
       def self.from_response(response)
         xml = XML.new(response.body)
 

src/awscr-s3/multipart_file_uploader.cr

@@ -24,6 +24,7 @@ module Awscr::S3
       @channel = Channel(Nil).new
     end
 
+    # Uploads an *object* to a *bucket*, in multiple parts
     def upload(bucket : String, object : String, io : IO, headers : Hash(String, String) = Hash(String, String).new)
       @bucket = bucket
       @object = object

src/awscr-s3/object.cr

@@ -1,8 +1,13 @@
 module Awscr::S3
   # An object on S3
   class Object
+    # The key of the `Object`
     getter key
+
+    # The size of the `Object`, in bytes
     getter size
+
+    # The `Object` etag
     getter etag
 
     def initialize(@key : String, @size : Int32, @etag : String)

src/awscr-s3/paginators/list_object_v2.cr

@@ -1,4 +1,5 @@
 module Awscr::S3::Paginator
+  # Paginates a `Response::ListObjectsV2` based on the continuation-token.
   class ListObjectsV2
     include Iterator(Response::ListObjectsV2)
 
@@ -11,6 +12,7 @@ module Awscr::S3::Paginator
       @last_output = nil
     end
 
+    # :nodoc:
     def next
       return stop if (lo = @last_output) && !lo.truncated?
 
@@ -21,10 +23,12 @@ module Awscr::S3::Paginator
       @last_output = Response::ListObjectsV2.from_response(next_response)
     end
 
+    # :nodoc:
     private def next_response
       @http.get("/#{@bucket}?#{query_string}")
     end
 
+    # :nodoc:
     private def query_string
       @params.map { |k, v| "#{k}=#{URI.escape(v.to_s)}" }.join("&")
     end

src/awscr-s3/presigned/post_field.cr

@@ -14,6 +14,7 @@ module Awscr
         def initialize(@key : String, @value : String)
         end
 
+        # Serialize the key into the format required for a `Presigned::Post`
         def serialize
           {@key => @value}
         end

src/awscr-s3/responses/complete_multipart_upload_output.cr

@@ -2,6 +2,8 @@ require "xml"
 
 module Awscr::S3::Response
   class CompleteMultipartUpload
+    # Create a `CompleteMultipartUpload` response from an
+    # `HTTP::Client::Response` object
     def self.from_response(response)
       xml = XML.new(response.body)
 
@@ -12,8 +14,13 @@ module Awscr::S3::Response
       new(location, key, etag)
     end
 
+    # The key of the uploaded object
     getter key
+
+    # The full location of the uploaded object
     getter location
+
+    # The etag of the uploaded object
     getter etag
 
     def initialize(@location : String, @key : String, @etag : String)

src/awscr-s3/responses/get_object_output.cr

@@ -2,8 +2,11 @@ require "xml"
 
 module Awscr::S3::Response
   class GetObjectOutput
+    # The body of the request object
     getter body
 
+    # Create a `GetObjectOutput` response from an
+    # `HTTP::Client::Response` object
     def self.from_response(response)
       new(response.body)
     end

src/awscr-s3/responses/list_all_my_buckets.cr

@@ -7,6 +7,8 @@ module Awscr::S3::Response
     # :nodoc:
     DATE_FORMAT = "%Y-%M-%dT%H:%M:%S.%z"
 
+    # Create a `ListAllMyBuckets` response from an
+    # `HTTP::Client::Response` object
     def self.from_response(response)
       xml = XML.new(response.body)
 
@@ -24,11 +26,13 @@ module Awscr::S3::Response
       new(buckets)
     end
 
+    # The array of buckets
     getter buckets
 
     def initialize(@buckets : Array(Bucket))
     end
 
+    # Iterate over each bucket in the response
     def each(&block)
       @buckets.each { |b| yield b }
     end

src/awscr-s3/responses/list_objects_v2.cr

@@ -3,6 +3,8 @@ require "uri"
 
 module Awscr::S3::Response
   class ListObjectsV2
+    # Create a `ListObjectsV2` response from an
+    # `HTTP::Client::Response` object
     def self.from_response(response)
       xml = XML.new(response.body)
 
@@ -25,16 +27,19 @@ module Awscr::S3::Response
       new(name, prefix, key_count.to_i, max_keys.to_i, truncated == "true", token, objects)
     end
 
+    # The list of obects
     getter contents
 
     def initialize(@name : String, @prefix : String, @key_count : Int32,
                    @max_keys : Int32, @truncated : Bool, @continuation_token : String, @contents : Array(Object))
     end
 
+    # The continuation token for the subsequent response, if any
     def next_token
       @continuation_token
     end
 
+    # Returns true if the response is truncated, false otherwise
     def truncated?
       @truncated
     end

src/awscr-s3/responses/put_object_output.cr

@@ -2,10 +2,15 @@ require "xml"
 
 module Awscr::S3::Response
   class PutObjectOutput
+    # Create a `PutObjectOutput` response from an
+    # `HTTP::Client::Response` object
     def self.from_response(response)
       new(response.headers["ETag"])
     end
 
+    # The etag of the new object
+    getter etag
+
     def initialize(@etag : String)
     end
 

src/awscr-s3/responses/start_multipart_upload.cr

@@ -2,6 +2,8 @@ require "xml"
 
 module Awscr::S3::Response
   class StartMultipartUpload
+    # Create a `StartMultipartUpload` response from an
+    # `HTTP::Client::Response` object
     def self.from_response(response)
       xml = XML.new(response.body)
 
@@ -12,8 +14,13 @@ module Awscr::S3::Response
       new(bucket, key, upload_id)
     end
 
+    # The key for the object
     getter key
+
+    # The bucket for the object
     getter bucket
+
+    # The ID of the new object
     getter upload_id
 
     def initialize(@bucket : String, @key : String, @upload_id : String)

src/awscr-s3/responses/upload_part_output.cr

@@ -2,8 +2,13 @@ require "xml"
 
 module Awscr::S3::Response
   class UploadPartOutput
+    # The etag of the uploaded part
     getter etag
+
+    # The part number
     getter part_number
+
+    # The upload id for the uploaded part
     getter upload_id
 
     def initialize(@etag : String, @part_number : Int32, @upload_id : String)

src/awscr-s3/signer_factory.cr

@@ -3,7 +3,7 @@ module Awscr
     # Fetches an `Awscr::Signer::Signers` based on the signing version
     # requested, and configures it with the region, key and secret.
     class SignerFactory
-      # Fetch and configure a signer
+      # Fetch and configure a signer based on a version algorithm
       def self.get(region : String, aws_access_key : String,
                    aws_secret_key : String, version : Symbol)
         case version

src/awscr-s3/xml.cr

@@ -53,6 +53,7 @@ module Awscr::S3
       @xml = NamespacedNode.new(::XML.parse(xml))
     end
 
+    # :nodoc:
     forward_missing_to @xml
   end
 end