harkness 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bde0dd383b950752ad75505b15a0b9f4a3d0a8fd63339136ec03a625f0c371c8
-  data.tar.gz: 1e158b73d045f626ca673be4b5e6588ce018d5a9384c97d74a223d52c628e7a9
+  metadata.gz: 306a55aff7abd2df10be5d952209fddbfd66125d4928c2b857fab9a78a89225d
+  data.tar.gz: 47a9be14d3e650d34129548872e36eeaa2696026a57e67ac10099ec7833c180a
 SHA512:
-  metadata.gz: 3eaf2fc1c274671c6970e7f6ed4b26c1fc4e4dcebb73a83b074243f8a180ea04ef69215aa0cef79270b50f36d9bf2d6dfbe7f352d2976d5e6d0d485091f316ba
-  data.tar.gz: 6ccf1aca3a8baf4d90505a25fe99debbb6636f987b99de187f717c4d033960127c8fd402ac8b82bd5f25a4f4e53160bc1965958ace2868c62a71862ad6233ebc
+  metadata.gz: 7a5b6517f178ba753effdbe164cbb881c7d6b8246055c6d05eba6e3a74fca02caf2036e836fa3502cd9b9b79082a03e8bff24fe7e7b4dfbb75f71a33eccb395b
+  data.tar.gz: 0eaadb16b2961eee7eac183dcb7455e5a663bf3552db57395e295ace79e28024dfc9a44f9f586fa406f3a1819c2873636a18cff8edfafa0b2c7a322b679f218f

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [1.1.0](https://github.com/duffn/harkness/compare/v1.0.0...v1.1.0) (2023-03-13)
+
+
+### Features
+
+* Add additional code docs ([#7](https://github.com/duffn/harkness/issues/7)) ([8fead00](https://github.com/duffn/harkness/commit/8fead007d888b79bcd6e54afd8705dafea390a16))
+* Add yard docs for Comic, ComicList, and related classes ([ab12e30](https://github.com/duffn/harkness/commit/ab12e300cee37c32e0a55b1198bb866518b53643))
+
+
+### Bug Fixes
+
+* add missing `returned` attribute for some summary models ([#5](https://github.com/duffn/harkness/issues/5)) ([2339e9c](https://github.com/duffn/harkness/commit/2339e9c20be0860640970a9701437e98f0b60f66))
+
 ## [1.0.0] (2023-03-12)
 
 - Initial release

data/README.md

@@ -2,7 +2,7 @@
 
 A full-featured and painstakingly documented library for working (playing) with the [Marvel API](https://developer.marvel.com/docs).
 
-![main](https://github.com/duffn/harkness/actions/workflows/test.yml/badge.svg) [![codecov](https://codecov.io/gh/duffn/harkness/branch/main/graph/badge.svg?token=9XUA33QIM2)](https://codecov.io/gh/duffn/harkness)
+![main](https://github.com/duffn/harkness/actions/workflows/test.yml/badge.svg) [![codecov](https://codecov.io/gh/duffn/harkness/branch/main/graph/badge.svg?token=9XUA33QIM2)](https://codecov.io/gh/duffn/harkness) [![Gem Version](https://badge.fury.io/rb/harkness.svg)](https://badge.fury.io/rb/harkness)
 
 ## Installation
 

data/lib/harkness/error.rb

@@ -2,6 +2,7 @@
 
 module Harkness
   module Error
+    # Base Harkness error class.
     class Error < StandardError; end
 
     # Raised when the API endpoint returns the HTTP status code 400.

data/lib/harkness/models/base/data_container.rb

@@ -5,16 +5,16 @@ module Harkness
     # Container class that holds pagination information.
     class DataContainer < Shale::Mapper
       # @!attribute [r] offset
-      #   @return [Integer] the requested offset (number of skipped results) of the call.
+      # @return [Integer] the requested offset (number of skipped results) of the call.
       attribute :offset, Shale::Type::Integer
       # @!attribute [r] limit
-      #   @return [Integer] the requested result limit.
+      # @return [Integer] the requested result limit.
       attribute :limit, Shale::Type::Integer
       # @!attribute [r] total
-      #   @return [Integer] the total number of resources available given the current filter set.
+      # @return [Integer] the total number of resources available given the current filter set.
       attribute :total, Shale::Type::Integer
       # @!attribute [r] count
-      #   @return [Integer] the total number of results returned by this call.
+      # @return [Integer] the total number of results returned by this call.
       attribute :count, Shale::Type::Integer
     end
   end

data/lib/harkness/models/base/data_wrapper.rb

@@ -5,29 +5,29 @@ module Harkness
     # The top level wrapper of a response from the API.
     class DataWrapper < Shale::Mapper
       # @!attribute [r] code
-      #   @return [Integer] the HTTP status code of the returned result.
+      # @return [Integer] the HTTP status code of the returned result.
       attribute :code, Shale::Type::Integer
       # @!attribute [r] status
-      #   @return [String] a string description of the call status.
+      # @return [String] a string description of the call status.
       attribute :status, Shale::Type::String
       # @!attribute [r] copyright
-      #   @return [String] the copyright notice for the returned result.
+      # @return [String] the copyright notice for the returned result.
       attribute :copyright, Shale::Type::String
       # @!attribute [r] attributionText
-      #   @return [String] the attribution notice for this result.
-      #     Please display either this notice or the contents of the attributionHTML field on all
-      #     screens which contain data from the Marvel Comics API.
+      # @return [String] the attribution notice for this result.
+      #   Please display either this notice or the contents of the attributionHTML field on all
+      #   screens which contain data from the Marvel Comics API.
       attribute :attributionText, Shale::Type::String
       # @!attribute [r] attributionHTML
-      #   @return [String] an HTML representation of the attribution notice for this result.
-      #     Please display either this notice or the contents of the attributionText field on all
-      #     screens which contain data from the Marvel Comics API.
+      # @return [String] an HTML representation of the attribution notice for this result.
+      #   Please display either this notice or the contents of the attributionText field on all
+      #   screens which contain data from the Marvel Comics API.
       attribute :attributionHTML, Shale::Type::String
       # @!attribute [r] data
-      #   @return [Harkness::Base::DataContainer] the results returned by the call.
+      # @return [Harkness::Base::DataContainer] the results returned by the call.
       attribute :data, Harkness::Base::DataContainer
       # @!attribute [r] etag
-      #   @return [String] a digest value of the content returned by the call.
+      # @return [String] a digest value of the content returned by the call.
       attribute :etag, Shale::Type::String
     end
   end

data/lib/harkness/models/base/summary.rb

@@ -7,10 +7,10 @@ module Harkness
     #   one of the summary objects is a Series.
     class Summary < Shale::Mapper
       # @!attribute [r] resourceURI
-      #   @return [String] the path to the individual resource.
+      # @return [String] the path to the individual resource.
       attribute :resourceURI, Shale::Type::String
       # @!attribute [r] name
-      #   @return [String] the canonical name of the resource.
+      # @return [String] the canonical name of the resource.
       attribute :name, Shale::Type::String
     end
   end

data/lib/harkness/models/character.rb

@@ -4,51 +4,51 @@ module Harkness
   # An individual character.
   class Character < Shale::Mapper
     # @!attribute [r] id
-    #   @return [Integer] the unique ID of the character resource.
+    # @return [Integer] the unique ID of the character resource.
     attribute :id, Shale::Type::Integer
     # @!attribute [r] name
-    #   @return [String] the name of the character.
+    # @return [String] the name of the character.
     attribute :name, Shale::Type::String
     # @!attribute [r] description
-    #   @return [String] a short bio or description of the character
+    # @return [String] a short bio or description of the character
     attribute :description, Shale::Type::String
     # @!attribute [r] modified
-    #   @return [String] the date the resource was most recently modified.
+    # @return [String] the date the resource was most recently modified.
     attribute :modified, Shale::Type::String
     # @!attribute [r] resourceURI
-    #   @return [String] the canonical URL identifier for this resource.
+    # @return [String] the canonical URL identifier for this resource.
     attribute :resourceURI, Shale::Type::String
     # @!attribute [r] urls
-    #   @return [Array<Harkness::URL>] a set of public web site URLs for the resource.
+    # @return [Array<Harkness::URL>] a set of public web site URLs for the resource.
     attribute :urls, Harkness::URL, collection: true
     # @!attribute [r] thumbnail
-    #   @return [Harkness::Image] the representative image for this character.
+    # @return [Harkness::Image] the representative image for this character.
     attribute :thumbnail, Harkness::Image
     # @!attribute [r] comics
-    #   @return [Harkness::ComicList] a resource list containing comics which feature this character.
+    # @return [Harkness::ComicList] a resource list containing comics which feature this character.
     attribute :comics, Harkness::ComicList
     # @!attribute [r] stories
-    #   @return [Harkness::StoryList] a resource list of stories in which this character appears.
+    # @return [Harkness::StoryList] a resource list of stories in which this character appears.
     attribute :stories, Harkness::StoryList
     # @!attribute [r] events
-    #   @return [Harkness::EventList] a resource list of events in which this character appears.
+    # @return [Harkness::EventList] a resource list of events in which this character appears.
     attribute :events, Harkness::EventList
     # @!attribute [r] series
-    #   @return [Harkness::SeriesList] a resource list of series in which this character appears.
+    # @return [Harkness::SeriesList] a resource list of series in which this character appears.
     attribute :series, Harkness::SeriesList
   end
 
-  # Container class that holds pagination information and results
+  # Container class that holds pagination information and results.
   class CharacterDataContainer < Harkness::Base::DataContainer
     # @!attribute [r] results
-    #   @return [Array<Harkness::Character>] the list of characters returned by the call.
+    # @return [Array<Harkness::Character>] the list of characters returned by the call.
     attribute :results, Harkness::Character, collection: true
   end
 
   # The top level wrapper of a response from the API.
   class CharacterDataWrapper < Harkness::Base::DataWrapper
     # @!attribute [r] data
-    #   @return [CharacterDataContainer] the results returned by the call.
+    # @return [Harkness::CharacterDataContainer] the results returned by the call.
     attribute :data, Harkness::CharacterDataContainer
   end
 end

data/lib/harkness/models/character_list.rb

@@ -4,24 +4,24 @@ module Harkness
   # The summary of a character.
   class CharacterSummary < Harkness::Base::Summary
     # @!attribute [r] role
-    #   @return [String] the role of the creator in the parent entity.
+    # @return [String] the role of the character in the parent entity.
     attribute :role, Shale::Type::String
   end
 
   # A list of characters.
   class CharacterList < Shale::Mapper
     # @!attribute [r] available
-    #   @return [Integer] the number of total available characters in this list.
-    #     Will always be greater than or equal to the "returned" value.
+    # @return [Integer] the number of total available characters in this list.
+    #   Will always be greater than or equal to the "returned" value.
     attribute :available, Shale::Type::Integer
     # @!attribute [r] returned
-    #   @return [Integer] the number of characters returned in this collection (up to 20).
+    # @return [Integer] the number of characters returned in this collection (up to 20).
     attribute :returned, Shale::Type::Integer
     # @!attribute [r] collectionURI
-    #   @return [String] the path to the full list of characters in this collection.
+    # @return [String] the path to the full list of characters in this collection.
     attribute :collectionURI, Shale::Type::String
-    # @!attribute [r] offset
-    #   @return [Array<Harkness::CharacterSummary>] the list of returned characters in this collection.
+    # @!attribute [r] items
+    # @return [Array<Harkness::CharacterSummary>] the list of returned characters in this collection.
     attribute :items, Harkness::CharacterSummary, collection: true
   end
 end

data/lib/harkness/models/comic.rb

@@ -1,53 +1,133 @@
 # frozen_string_literal: true
 
 module Harkness
+  # The data of a comic.
   class ComicDate < Shale::Mapper
+    # @!attribute [r] type
+    # @return [String] a description of the date (e.g. onsale date, FOC date).
     attribute :type, Shale::Type::String
+    # @!attribute [r] date
+    # @return [String] the date.
     attribute :date, Shale::Type::String
   end
 
+  # The price of a comic.
   class ComicPrice < Shale::Mapper
+    # @!attribute [r] type
+    # @return [String] a description of the price (e.g. print price, digital price).
     attribute :type, Shale::Type::String
+    # @!attribute [r] price
+    # @return [Float] the price (all prices in USD).
     attribute :price, Shale::Type::Float
   end
 
+  # An individual character.
   class Comic < Shale::Mapper
+    # @!attribute [r] id
+    # @return [Integer] the unique ID of the comic resource.
     attribute :id, Shale::Type::Integer
+    # @!attribute [r] digitalId
+    # @return [Integer] the ID of the digital comic representation of this comic. Will be 0 if the comic is
+    #   not available digitally.
     attribute :digitalId, Shale::Type::Integer
+    # @!attribute [r] title
+    # @return [String] the canonical title of the comic.
     attribute :title, Shale::Type::String
+    # @!attribute [r] issueNumber
+    # @return [Integer] the number of the issue in the series (will generally be 0 for collection formats).
     attribute :issueNumber, Shale::Type::Integer
+    # @!attribute [r] variantDescription
+    # @return [String] If the issue is a variant (e.g. an alternate cover, second printing, or director’s cut),
+    #   a text description of the variant.
     attribute :variantDescription, Shale::Type::String
+    # @!attribute [r] description
+    # @return [String] the preferred description of the comic.
     attribute :description, Shale::Type::String
+    # @!attribute [r] modified
+    # @return [String] the date the resource was most recently modified.
     attribute :modified, Shale::Type::String
+    # @!attribute [r] isbn
+    # @return [String] the ISBN for the comic (generally only populated for collection formats).
     attribute :isbn, Shale::Type::String
+    # @!attribute [r] upc
+    # @return [String] the UPC barcode number for the comic (generally only populated for periodical formats).
     attribute :upc, Shale::Type::String
+    # @!attribute [r] diamondCode
+    # @return [String] the Diamond code for the comic.
     attribute :diamondCode, Shale::Type::String
+    # @!attribute [r] ean
+    # @return [String] the EAN barcode for the comic.
     attribute :ean, Shale::Type::String
+    # @!attribute [r] issn
+    # @return [String] the ISSN barcode for the comic.
     attribute :issn, Shale::Type::String
+    # @!attribute [r] format
+    # @return [String] the publication format of the comic e.g. comic, hardcover, trade paperback.
     attribute :format, Shale::Type::String
+    # @!attribute [r] pageCount
+    # @return [Integer] the number of story pages in the comic.
     attribute :pageCount, Shale::Type::Integer
+    # @!attribute [r] textObjects
+    # @return [Array<Harkness::TextObject>] a set of descriptive text blurbs for the comic.
     attribute :textObjects, Harkness::TextObject, collection: true
+    # @!attribute [r] resourceURI
+    # @return [String] the canonical URL identifier for this resource.
     attribute :resourceURI, Shale::Type::String
+    # @!attribute [r] urls
+    # @return [Array<Harkness::URL>] a set of public web site URLs for the resource.
     attribute :urls, Harkness::URL, collection: true
+    # @!attribute [r] series
+    # @return [Array<Harkness::SeriesSummary>] a summary representation of the series to which this comic belongs.
     attribute :series, Harkness::SeriesSummary
+    # @!attribute [r] variants
+    # @return [Array<Harkness::ComicSummary>] a list of variant issues for this comic (includes the "original" issue
+    #   if the current issue is a variant).
     attribute :variants, Harkness::ComicSummary, collection: true
+    # @!attribute [r] collections
+    # @return [Array<Harkness::ComicSummary>] A list of collections which include this comic (will generally
+    #   be empty if the comic's format is a collection).
     attribute :collections, Harkness::ComicSummary, collection: true
+    # @!attribute [r] collectedIssues
+    # @return [Array<Harkness::ComicSummary>] a list of issues collected in this comic (will generally
+    #   be empty for periodical formats such as "comic" or "magazine").
     attribute :collectedIssues, Harkness::ComicSummary, collection: true
+    # @!attribute [r] dates
+    # @return [Array<Harkness::ComicDate] a list of key dates for this comic.
     attribute :dates, Harkness::ComicDate, collection: true
+    # @!attribute [r] prices
+    # @return [Array<Harkness::ComicPrice>] a list of prices for this comic.
     attribute :prices, Harkness::ComicPrice, collection: true
+    # @!attribute [r] thumbnail
+    # @return [Harkness::Image] the representative image for this comic.
     attribute :thumbnail, Harkness::Image
+    # @!attribute [r] images
+    # @return [Array<Harkness::Image>] a list of promotional images associated with this comic.
     attribute :images, Harkness::Image, collection: true
+    # @!attribute [r] creators
+    # @return [Harkness::CreatorList] a resource list containing the creators associated with this comic.
     attribute :creators, Harkness::CreatorList
+    # @!attribute [r] characters
+    # @return [Harkness::CharacterList] a resource list containing the characters which appear in this comic.
     attribute :characters, Harkness::CharacterList
+    # @!attribute [r] stories
+    # @return [Harkness::StoryList] a resource list containing the stories which appear in this comic.
     attribute :stories, Harkness::StoryList
+    # @!attribute [r] events
+    # @return [Harkness::EventList] a resource list containing the events in which this comic appears.
     attribute :events, Harkness::EventList
   end
 
+  # Container class that holds pagination information and results.
   class ComicDataContainer < Harkness::Base::DataContainer
+    # @!attribute [r] results
+    # @return [Array<Harkness::Comic>] the list of comics returned by the call.
     attribute :results, Harkness::Comic, collection: true
   end
 
+  # The top level wrapper of a response from the API.
   class ComicDataWrapper < Harkness::Base::DataWrapper
+    # @!attribute [r] data
+    # @return [Harkness::ComicDataContainer] The results returned by the call.
     attribute :data, Harkness::ComicDataContainer
   end
 end

data/lib/harkness/models/comic_list.rb

@@ -1,12 +1,24 @@
 # frozen_string_literal: true
 
 module Harkness
+  # The summary of a comic.
   class ComicSummary < Harkness::Base::Summary
   end
 
+  # A list of comics.
   class ComicList < Shale::Mapper
+    # @!attribute [r] available
+    # @return [Integer] the number of total available issues in this list. Will always be greater than
+    #   or equal to the "returned" value.
     attribute :available, Shale::Type::Integer
+    # @!attribute [r] returned
+    # @return [Integer] the number of comics returned in this collection (up to 20).
+    attribute :returned, Shale::Type::Integer
+    # @!attribute [r] collectionURI
+    # @return [String] the path to the full list of issues in this collection.
     attribute :collectionURI, Shale::Type::String
+    # @!attribute [r] collectionURI
+    # @return [Array<Harkness::ComicSummary>] the list of returned issues in this collection.
     attribute :items, Harkness::ComicSummary, collection: true
   end
 end

data/lib/harkness/models/creator.rb

@@ -1,28 +1,63 @@
 # frozen_string_literal: true
 
 module Harkness
+  # An individual creator.
   class Creator < Shale::Mapper
+    # @!attribute [r] id
+    # @return [Integer] the unique ID of the creator resource.
     attribute :id, Shale::Type::Integer
+    # @!attribute [r] firstName
+    # @return [String] the first name of the creator.
     attribute :firstName, Shale::Type::String
+    # @!attribute [r] middleName
+    # @return [String] the middle name of the creator.
     attribute :middleName, Shale::Type::String
+    # @!attribute [r] lastName
+    # @return [String] tThe last name of the creator.
     attribute :lastName, Shale::Type::String
+    # @!attribute [r] suffix
+    # @return [String] the suffix or honorific for the creator.
     attribute :suffix, Shale::Type::String
+    # @!attribute [r] fullName
+    # @return [String] the full name of the creator (a space-separated concatenation of the above four fields).
     attribute :fullName, Shale::Type::String
+    # @!attribute [r] modified
+    # @return [String] the date the resource was most recently modified.
     attribute :modified, Shale::Type::String
+    # @!attribute [r] resourceURI
+    # @return [String] the canonical URL identifier for this resource.
     attribute :resourceURI, Shale::Type::String
+    # @!attribute [r] urls
+    # @return [Array<Harkness::URL>] a set of public web site URLs for the resource.
     attribute :urls, Harkness::URL, collection: true
+    # @!attribute [r] thumbnail
+    # @return [Harkness::Image] the representative image for this creator.
     attribute :thumbnail, Harkness::Image
+    # @!attribute [r] series
+    # @return [Harkness::SeriesList] a resource list containing the series which feature work by this creator
     attribute :series, Harkness::SeriesList
+    # @!attribute [r] stories
+    # @return [Harkness::StoryList] A resource list containing the stories which feature work by this creator.
     attribute :stories, Harkness::StoryList
+    # @!attribute [r] comics
+    # @return [Harkness::ComicList] a resource list containing the comics which feature work by this creator.
     attribute :comics, Harkness::ComicList
+    # @!attribute [r] events
+    # @return [Harkness::EventList] a resource list containing the events which feature work by this creator.
     attribute :events, Harkness::EventList
   end
 
+  # Container class that holds pagination information and results.
   class CreatorDataContainer < Harkness::Base::DataContainer
+    # @!attribute [r] results
+    # @return [Array<Harkness::Creator>] the list of creators returned by the call.
     attribute :results, Harkness::Creator, collection: true
   end
 
+  # The top level wrapper of a response from the API.
   class CreatorDataWrapper < Harkness::Base::DataWrapper
+    # @!attribute [r] data
+    # @return [Harkness::CreatorDataContainer] the results returned by the call.
     attribute :data, Harkness::CreatorDataContainer
   end
 end

data/lib/harkness/models/creator_list.rb

@@ -1,14 +1,27 @@
 # frozen_string_literal: true
 
 module Harkness
+  # The summary of a creator.
   class CreatorSummary < Harkness::Base::Summary
+    # @!attribute [r] role
+    # @return [String] the role of the creator in the parent entity.
     attribute :role, Shale::Type::String
   end
 
+  # A list of creators.
   class CreatorList < Shale::Mapper
+    # @!attribute [r] available
+    # @return [Integer] the number of total available creators in this list.
+    #   Will always be greater than or equal to the "returned" value.
     attribute :available, Shale::Type::Integer
+    # @!attribute [r] returned
+    # @return [Integer] the number of creators returned in this collection (up to 20).
     attribute :returned, Shale::Type::Integer
+    # @!attribute [r] collectionURI
+    # @return [String] the path to the full list of creators in this collection.
     attribute :collectionURI, Shale::Type::String
+    # @!attribute [r] offset
+    # @return [Array<Harkness::CreatorySummary>] the list of returned creators in this collection.
     attribute :items, Harkness::CreatorSummary, collection: true
   end
 end

data/lib/harkness/models/event_list.rb

@@ -1,12 +1,24 @@
 # frozen_string_literal: true
 
 module Harkness
+  # The summary of an event.
   class EventSummary < Harkness::Base::Summary
   end
 
+  # A list of events.
   class EventList < Shale::Mapper
+    # @!attribute [r] available
+    # @return [Integer] the number of total available events in this list.
+    #   Will always be greater than or equal to the "returned" value.
     attribute :available, Shale::Type::Integer
+    # @!attribute [r] returned
+    # @return [Integer] the number of events returned in this collection (up to 20).
+    attribute :returned, Shale::Type::Integer
+    # @!attribute [r] collectionURI
+    # @return [String] the path to the full list of events in this collection.
     attribute :collectionURI, Shale::Type::String
+    # @!attribute [r] items
+    # @return [Array<Harkness::EventSummary>] the list of returned characters in this collection.
     attribute :items, Harkness::EventSummary, collection: true
   end
 end

data/lib/harkness/models/image.rb

@@ -3,7 +3,11 @@
 module Harkness
   # An image.
   class Image < Shale::Mapper
+    # @!attribute [r] path
+    # @return [String] the directory path of to the image.,
     attribute :path, Shale::Type::String
+    # @!attribute [r] extension
+    # @return [String] the file extension for the image.
     attribute :extension, Shale::Type::String
   end
 end

data/lib/harkness/models/series.rb

@@ -1,32 +1,72 @@
 # frozen_string_literal: true
 
 module Harkness
+  # An individual series.
   class Series < Shale::Mapper
+    # @!attribute [r] id
+    # @return [Integer] the unique ID of the series resource.
     attribute :id, Shale::Type::Integer
+    # @!attribute [r] title
+    # @return [String] the canonical title of the series.
     attribute :title, Shale::Type::String
+    # @!attribute [r] description
+    # @return [String] a description of the series.
     attribute :description, Shale::Type::String
+    # @!attribute [r] resourceURI
+    # @return [String] the canonical URL identifier for this resource.
     attribute :resourceURI, Shale::Type::String
+    # @!attribute [r] urls
+    # @return [Array<Harkness::URL>] a set of public web site URLs for the resource.
     attribute :urls, Harkness::URL, collection: true
-
+    # @!attribute [r] startYear
+    # @return [Integer] the first year of publication for the series.
     attribute :startYear, Shale::Type::Integer
+    # @!attribute [r] endYear
+    # @return [Integer] the last year of publication for the series (conventionally, 2099 for ongoing series).
     attribute :endYear, Shale::Type::Integer
+    # @!attribute [r] rating
+    # @return [String] the age-appropriateness rating for the series.
     attribute :rating, Shale::Type::String
+    # @!attribute [r] modified
+    # @return [String] the date the resource was most recently modified.
     attribute :modified, Shale::Type::String
+    # @!attribute [r] thumbnail
+    # @return [Harkness::Image] the representative image for this SERIES.
     attribute :thumbnail, Harkness::Image
+    # @!attribute [r] comics
+    # @return [Harkness::ComicList] : a resource list containing comics in this series.
     attribute :comics, Harkness::ComicList
+    # @!attribute [r] stories
+    # @return [Harkness::StoryList] a resource list containing stories which occur in comics in this series.
     attribute :stories, Harkness::StoryList
+    # @!attribute [r] events
+    # @return [Harkness::EventList] a resource list containing events which take place in comics in this series.
     attribute :events, Harkness::EventList
+    # @!attribute [r] characters
+    # @return [Harkness::CharacterList] a resource list containing characters which appear in comics in this series.
     attribute :characters, Harkness::CharacterList
+    # @!attribute [r] creators
+    # @return [Harkness::CreatorList] a resource list of creators whose work appears in comics in this series.
     attribute :creators, Harkness::CreatorList
+    # @!attribute [r] next
+    # @return [Harkness::SeriesSummary] a summary representation of the series which follows this series.,
     attribute :next, Harkness::SeriesSummary
+    # @!attribute [r] next
+    # @return [Harkness::SeriesSummary] a summary representation of the series which preceded this series.
     attribute :previous, Harkness::SeriesSummary
   end
 
+  # Container class that holds pagination information and results.
   class SeriesDataContainer < Harkness::Base::DataContainer
+    # @!attribute [r] results
+    # @return [Array<Harkness::Series>] the list of series returned by the call.
     attribute :results, Harkness::Series, collection: true
   end
 
+  # The top level wrapper of a response from the API.
   class SeriesDataWrapper < Harkness::Base::DataWrapper
+    # @!attribute [r] data
+    # @return [Harkness::SeriesDataContainer] the results returned by the call.
     attribute :data, Harkness::SeriesDataContainer
   end
 end

data/lib/harkness/models/series_list.rb

@@ -1,12 +1,24 @@
 # frozen_string_literal: true
 
 module Harkness
+  # The summary of a series.
   class SeriesSummary < Harkness::Base::Summary
   end
 
+  # A list of series.
   class SeriesList < Shale::Mapper
+    # @!attribute [r] available
+    # @return [Integer] the number of total available series in this list.
+    #   Will always be greater than or equal to the "returned" value.
     attribute :available, Shale::Type::Integer
+    # @!attribute [r] returned
+    # @return [Integer] the number of series returned in this collection (up to 20).
+    attribute :returned, Shale::Type::Integer
+    # @!attribute [r] collectionURI
+    # @return [String] the path to the full list of series in this collection.
     attribute :collectionURI, Shale::Type::String
+    # @!attribute [r] items
+    # @return [Array<Harkness::SeriesSummary>] the list of returned characters in this collection.
     attribute :items, Harkness::SeriesSummary, collection: true
   end
 end

data/lib/harkness/models/story.rb

@@ -1,26 +1,58 @@
 # frozen_string_literal: true
 
 module Harkness
+  # An individual story
   class Story < Shale::Mapper
+    # @!attribute [r] id
+    # @return [Integer] the unique ID of the story resource.
     attribute :id, Shale::Type::Integer
+    # @!attribute [r] title
+    # @return [String] the canonical title of the story.
     attribute :title, Shale::Type::String
+    # @!attribute [r] description
+    # @return [String] a description of the story.
     attribute :description, Shale::Type::String
+    # @!attribute [r] resourceURI
+    # @return [String] the canonical URL identifier for this resource.
     attribute :resourceURI, Shale::Type::String
+    # @!attribute [r] type
+    # @return [String] ' the story type e.g. interior story, cover, text story.
     attribute :type, Shale::Type::String
+    # @!attribute [r] modified
+    # @return [String] the date the resource was most recently modified.
     attribute :modified, Shale::Type::String
+    # @!attribute [r] thumbnail
+    # @return [String] the representative image for this story.
     attribute :thumbnail, Harkness::Image
+    # @!attribute [r] comics
+    # @return [Harkness::ComicList]  a resource list containing comics in which this story takes place.
     attribute :comics, Harkness::ComicList
+    # @!attribute [r] series
+    # @return [Harkness::SeriesList] a resource list containing series in which this story appears.
     attribute :series, Harkness::SeriesList
+    # @!attribute [r] events
+    # @return [Harkness::EventList] a resource list of the events in which this story appears.
     attribute :events, Harkness::EventList
+    # @!attribute [r] characters
+    # @return [Harkness::CharacterList] a resource list of characters which appear in this story.
     attribute :characters, Harkness::CharacterList
+    # @!attribute [r] originalIssue
+    # @return [Harkness::ComicSummary] a summary representation of the issue in which this story was
+    #   originally published.
     attribute :originalIssue, Harkness::ComicSummary
   end
 
+  # Container class that holds pagination information and results.
   class StoryDataContainer < Harkness::Base::DataContainer
+    # @!attribute [r] results
+    # @return [Array<Harkness::Story>] the list of stories returned by the call.
     attribute :results, Harkness::Story, collection: true
   end
 
+  # The top level wrapper of a response from the API.
   class StoryDataWrapper < Harkness::Base::DataWrapper
+    # @!attribute [r] data
+    # @return [Harkness::StoryDataContainer] the results returned by the call.
     attribute :data, Harkness::StoryDataContainer
   end
 end

data/lib/harkness/models/story_list.rb

@@ -1,13 +1,27 @@
 # frozen_string_literal: true
 
 module Harkness
+  # The summary of a story.
   class StorySummary < Harkness::Base::Summary
+    # @!attribute [r] type
+    # @return [String] the type of the story (interior or cover)
     attribute :type, Shale::Type::String
   end
 
+  # A list of stories.
   class StoryList < Shale::Mapper
+    # @!attribute [r] available
+    # @return [Integer] the number of total available stories in this list.
+    #   Will always be greater than or equal to the "returned" value.
     attribute :available, Shale::Type::Integer
+    # @!attribute [r] returned
+    # @return [Integer] the number of stories returned in this collection (up to 20).
+    attribute :returned, Shale::Type::Integer
+    # @!attribute [r] collectionURI
+    # @return [String] the path to the full list of stories in this collection.
     attribute :collectionURI, Shale::Type::String
+    # @!attribute [r] items
+    # @return [Array<Harkness::StorySummary>] the list of returned characters in this collection.
     attribute :items, Harkness::StorySummary, collection: true
   end
 end

data/lib/harkness/models/text_object.rb

@@ -1,10 +1,16 @@
 # frozen_string_literal: true
 
 module Harkness
-  # A text objct
+  # A text object.
   class TextObject < Shale::Mapper
+    # @!attribute [r] type
+    # @return [String] the canonical type of the text object (e.g. solicit text, preview text, etc.).
     attribute :type, Shale::Type::String
+    # @!attribute [r] language
+    # @return [String] the IETF language tag denoting the language the text object is written in.
     attribute :language, Shale::Type::String
+    # @!attribute [r] text
+    # @return [String] the text.
     attribute :text, Shale::Type::String
   end
 end

data/lib/harkness/models/url.rb

@@ -3,7 +3,11 @@
 module Harkness
   # A URL.
   class URL < Shale::Mapper
+    # @!attribute [r] type
+    # @return [String] a text identifier for the URL.
     attribute :type, Shale::Type::String
+    # @!attribute [r] url
+    # @return [String] a full URL (including scheme, domain, and path).
     attribute :url, Shale::Type::String
   end
 end

data/lib/harkness/resource.rb

@@ -3,19 +3,33 @@
 require "digest/md5"
 
 module Harkness
+  # The base resource class.
   class Resource
+    # A Harkness client.
+    # @return [Harkness::Client] the Harkness client.
     attr_reader :client
 
+    # Initialize a new resource.
+    # @param client [Harkness::Client] the Harkness client.
     def initialize(client)
       @client = client
     end
 
     private
 
+    # Perform a GET request to a URL with params and headers.
+    # @param url [String] the URL to send the GET request to.
+    # @param params [Hash] URL query parameters to send with the request.
+    # @param headers [Hash] headers to send with the request
+    # @return [Faraday::Response, Harkness::Error] a Faraday response or Harkness:Error depending
+    #   upon the status code.
     def get_request(url, params: {}, headers: {})
       handle_response client.connection.get(url, authentication_params.merge(params), headers)
     end
 
+    # Generate the parameters necessary to authenticate with the Marvel API.
+    # See [`authorization`](https://developer.marvel.com/documentation/authorization) in the Marvel API documentation.
+    # @return [Hash] the calculated authentication parameters.
     def authentication_params
       timestamp = Time.now.to_i
       {
@@ -25,6 +39,10 @@ module Harkness
       }
     end
 
+    # Handles a response from the API.
+    # @param response [Faraday::Response] the Faraday::Response from the API request.
+    # @return [Faraday::Response, Harkness::Error] a Faraday response or Harkness:Error depending
+    #   upon the status code.
     def handle_response(response)
       error_klass = Harkness::Error::STATUS_MAPPINGS[response.status]
       message = JSON.parse(response.body)["status"] || "API request failed with an unknown error."

data/lib/harkness/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Harkness
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: harkness
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - duffn
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-03-12 00:00:00.000000000 Z
+date: 2023-03-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -247,7 +247,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.6
+rubygems_version: 3.4.8
 signing_key:
 specification_version: 4
 summary: A library for working (playing) with the Marvel API.