rubyhexagon 2.0.0 → 2.0.1

data/lib/rubyhexagon/api/user.rb

@@ -20,6 +20,7 @@ module Rubyhexagon
   # A class to interact with the e621 web interface.
   #
   # @author Maxine Michalski
+  # @api public
   # @since 1.4.0
   class User
     # @author Maxine Michalski
@@ -27,7 +28,8 @@ module Rubyhexagon
     # Fetch data for user
     #
     # @param user [Hash|E621::User] User data to fetch from
-    #
+    # @example Get user information
+    #   E621::User.show(id: 1) #=> E621::User
     # @return [E621::User]
     def self.show(user)
       unless (user.is_a?(Hash) && user[:id].is_a?(Integer)) ||
@@ -38,6 +40,13 @@ module Rubyhexagon
       new(E621::API.fetch(:user, :show, user))
     end
 
+    # @author Maxine Michalski
+    #
+    # Fetch a list of users
+    #
+    # @example Get list of users
+    #   E621::User.list(name: 'purple') #=> Array<E621::User>
+    # @return [E621::User]
     def self.list(query)
       raise ArgumentError, 'A Hash is required' unless query.is_a?(Hash)
       E621::API.fetch(:user, :index, query).map do |user|
@@ -45,6 +54,12 @@ module Rubyhexagon
       end
     end
 
+    # @author Maxine Michalski
+    #
+    # User information
+    # @example Get User Information
+    #   user.show #=> E621::User
+    # @return [E621::User]
     def show
       E621::User.new(E621::API.fetch(:user, :show, id: @id))
     end

data/lib/rubyhexagon/artist.rb

@@ -20,35 +20,59 @@ module Rubyhexagon
   # Class to hold information about an artist on e621
   #
   # @author Maxine Michalski
+  # @api public
   # @since 1.0.0
   class Artist
+    # Artist ID
+    # @example Get artist ID
+    #   artist.id #=> Integer
     # @return [Integer] id of artist
     attr_reader :id
 
+    # Artist name
+    # @example Get artist name
+    #   artist.name #=> String
     # @return [String] name of artist
     attr_reader :name
 
+    # Alternative names for artist
+    # @example Get alternative names for artist
+    #   artist.other_names #=> [] or Array<String>
     # @return [Array<String>] alternative names for artist
     attr_reader :other_names
 
+    # Group name for artist
+    # @example Get group name for artist
+    #   artist.group_name #=> String
     # @return [String] group name for artist
     attr_reader :group_name
 
+    # URLs to find artist
+    # @example Get parsed URIs for artist
+    #   artist.urls #=> Array<URI> or []
     # @return [Array<URI>] links to find artist
     attr_reader :urls
 
+    # Version of artist information
+    # @example Get version of this artist's information
+    #   artist.version #=> Integer
     # @return [Integer] version of artist information
     attr_reader :version
 
+    # Updating user for this artist
+    # @example Get the user, who last updated this artist
+    #   artist.updater #=> E621::User
     # @return [E621::User] updating user
     attr_reader :updater
 
     # @author Maxine Michalski
     #
-    # Initializer for Artist.
+    # Initializer for Artist
     #
     # @param artist [Hash] artist data
-    #
+    # @example Get an artist instance
+    #   E621::Artist.new(id: 1) #=> E621::Artist instance
+    #   E621::Artist.new(name: 'artist') #=> E621::Artist instance
     # @return the object
     def initialize(artist)
       unless artist.is_a?(Hash)
@@ -72,7 +96,8 @@ module Rubyhexagon
     # @author Maxine Michalski
     #
     # Comparison method for artists
-    #
+    # @example Compare two tags, that are unequal
+    #   Tag.new(id: 1) == Tag.new(id: 2) #=> false
     # @return [TrueClass, FalseClass]
     def ==(other)
       return false unless other.is_a?(Artist)
@@ -82,23 +107,58 @@ module Rubyhexagon
     # @author Maxine Michalski
     #
     # Check if this artist is active
-    #
-    # @return [TrueClass] artist is active
-    # @return [FalseClass] artist is not active
+    # @example Is artist active?
+    #   artist.active? #=> true or false
+    # @return [TrueClass|FalseClass] depending on active status
     def active?
       @is_active
     end
 
+    # @author Maxine Michalski
+    #
+    # Turn object into a hash representation of itself
+    #
+    # @example Turn a User into a Hash
+    #   Tag.new(id: 1).to_hash #=> { id: 1 }
+    # @return [Hash]
+    def to_hash
+      hash = {}
+      instance_variables.each do |i|
+        hash.store(i.to_s.sub(/^@/, '').to_sym, instance_variable_get(i))
+      end
+      hash
+    end
+
     private
 
+    # @author Maxine Michalski
+    #
+    # Setup other names for artist
+    #
+    # @param names [String] comma separated list of names
+    # @api private
+    # @return [Array<String>]
     def setup_other_names(names)
       @other_names = names.split(',')
     end
 
+    # @author Maxine Michalski
+    #
+    # Parsed URI to find artist
+    #
+    # @param urls [Array<String>] urls to parse
+    # @api private
+    # @return [Array<URI>]
     def setup_urls(urls)
       @urls = urls.map { |u| URI.parse(u) }
     end
 
+    # @author Maxine Michalski
+    #
+    # Setup updating user
+    # @param updater [Integer] ID of the user who last updated
+    # @api private
+    # @return [E621::User]
     def setup_updater_id(updater)
       @updater = E621::User.new(id: updater)
     end

data/lib/rubyhexagon/error.rb

@@ -21,22 +21,3 @@
 # @author Maxine Michalski
 # @since 1.0.0
 class InvalidIDError < StandardError; end
-
-# Error class to show that an object misses an important parameter
-#
-# @author Maxine Michalski
-# @since 1.0.0
-class ObjectNotFilledError < StandardError; end
-
-module Rubyhexagon
-  # Error class to denote that API access was not permitted.
-  #
-  # @author Maxine Michalski
-  # @since 1.6.0
-  class AccessDenied < StandardError; end
-  # Error class that is raised by attempting write access.
-  #
-  # @author Maxine Michalski
-  # @since 2.0.0
-  class APIWriteError < StandardError; end
-end

data/lib/rubyhexagon/pool.rb

@@ -21,30 +21,57 @@ module Rubyhexagon
   # more Ruby like manner.
   #
   # @author Maxine Michalski
+  # @api public
   # @since 1.4.0
   class Pool
+    # Pool ID
+    # @example Get pool ID
+    #   pool.id #=> Integer
     # @return [Integer] returns this pool's ID
     attr_reader :id
 
+    # Pool name
+    # @example Get pool name
+    #   pool.name #=> String
     # @return [String] returns name of current pool
     attr_reader :name
 
+    # Pool creation time
+    # @example Get pool creation time
+    #   pool.created_at #=> Time
     # @return [Time] returns creation time
     attr_reader :created_at
 
+    # Time of last update to pool
+    # @example Get last update time of pool
+    #   pool.updated_at #=> Time
     # @return [Time] returns time of last update
     attr_reader :updated_at
 
+    # Pool description
+    # @example Get pool description
+    #   pool.description #=> String
     # @return [String] returns a description of the current pool
     attr_reader :description
 
+    # Number of posts, inside pool
+    # @example Get number of posts, pool has
+    #   pool.post_count #=> Integer
     # @return [Integer] returns number of posts inside pool
     attr_reader :post_count
 
+    # User who created pool
+    # @example Get user that created pool
+    #   pool.creator #=> E621::User
     # @return [E621::User] returns the user, who has created this pool
     attr_reader :creator
 
-    # @return [Array<Post>] returns an array of posts, that belong to this pool
+    # Posts of pool
+    #
+    # @example Get posts of pool
+    #   pool.posts #=> Array<E621::Post>
+    # @return [Array<E621::Post>] returns an array of posts, that belong to
+    # this pool
     attr_reader :posts
 
     # @author Maxine Michalski
@@ -52,7 +79,8 @@ module Rubyhexagon
     # Initializer for Pool objects
     #
     # @param pool [Hash] Pool information
-    #
+    # @example Get new pool instance
+    #   E621::Pool.new(id: 1) #=> E621::Pool instance
     # @return the object
     def initialize(pool)
       raise ArgumentError, "#{pool.class} is not a Hash" unless pool.is_a?(Hash)
@@ -76,8 +104,9 @@ module Rubyhexagon
     # @author Maxine Michalski
     #
     # Returns locking status
-    #
-    # @return [TrueClass,FalseClass]
+    # @example Test if pool is locked
+    #   pool.locked? #=> true or false
+    # @return [TrueClass|FalseClass]
     def locked?
       @is_locked
     end
@@ -85,8 +114,9 @@ module Rubyhexagon
     # @author Maxine Michalski
     #
     # Returns active status
-    #
-    # @return [TrueClass,FalseClass]
+    # @example Test if pool is active or not
+    #   pool.active? #=> true or false
+    # @return [TrueClass|FalseClass]
     def active?
       @is_active
     end
@@ -96,10 +126,26 @@ module Rubyhexagon
     # Comparison method for Pool objects
     #
     # @param other [Object] other object to compare
-    #
-    # @return [TrueClass,FalseClass]
+    # @example Comapring two unequal pools
+    #   Pool.new(id: 1) == Pool.new(id: 2) #=> false
+    # @return [TrueClass|FalseClass]
     def ==(other)
       other.is_a?(Pool) && @id == other.id && @updated_at == other.updated_at
     end
+
+    # @author Maxine Michalski
+    #
+    # Turn object into a hash representation of itself
+    #
+    # @example Turn a User into a Hash
+    #   E621::Pool.new(id: 1).to_hash #=> { id: 1 }
+    # @return [Hash]
+    def to_hash
+      hash = {}
+      instance_variables.each do |i|
+        hash.store(i.to_s.sub(/^@/, '').to_sym, instance_variable_get(i))
+      end
+      hash
+    end
   end
 end

data/lib/rubyhexagon/post.rb

@@ -21,73 +21,130 @@ module Rubyhexagon
   # more Ruby like manner.
   #
   # @author Maxine Michalski
+  # @api public
   # @since 1.0.0
   class Post
+    # Post ID
+    # @example Get post id
+    #   post.id #=> Integer
     # @return [Integer] id of post information
     attr_reader :id
 
+    # Post author
+    # @example Get post creator
+    #   post.author #=> E621::User
     # @return [E621::User] user object of who uploaded this post
     attr_reader :author
 
+    # Time post was created at
+    # @example Get creation time
+    #   post.created_at #=> Time
     # @return [Time] creation time of post
     attr_reader :created_at
 
+    # Post status
+    # @example Get post status
+    #   post.status #=> Symbol
     # @return [Symbol] status of post, can be :active, :flagged, :pending or
     #   :deleted
     attr_reader :status
 
+    # Post sources
+    # @example Get post sources
+    #   post.sources #=> Array<String>
     # @return [Array<String>] array of sources. This can contain URI in string
     #   form
     attr_reader :sources
 
+    # Post artists
+    #
+    # @example Get post artists
+    #   post.artists #=> Array<E621::Artist>
     # @return [Array<E621::Artist>] array of artists, that work on the image
     # in this post
     attr_reader :artists
 
-    # @return [String] description that's associated with this post
+    # Post desciption
+    # @example Get post description
+    #   post.description #=> String|nil
+    # @return [String|NilClass] description that's associated with this post
     attr_reader :description
 
+    # Count of users who favorited this post
+    # @example Get favorite count
+    #   post.fav_count #=> Integer
     # @return [Integer] number of people, who favorited this post
     attr_reader :fav_count
 
+    # Post score
+    # @example Get score assigned to post
+    #   post.score #=> Integer
     # @return [Integer] vote score this post holds
     attr_reader :score
 
+    # Post rating
+    # @example Get post rating
+    #   post.rating #=> Symbol
     # @return [Symbol] rating of this post. Can be one of :safe,
     #   :questionable, :explicit
     attr_reader :rating
 
+    # Post parent
+    # @example Get parent of post
+    #   post.parent #=> E621::Post or nil
     # @return [E621:post] parent of this post
     # @return [NilClass]
     attr_reader :parent
 
+    # Post children
+    # @example Get post's children
+    #   post.children #=> [] or Array<E621::Post>
     # @return [Array<E621::Post>] Array of child posts
     attr_reader :children
 
+    # Post MD5 checksum
+    # @example Get post's MD5 checksum
+    #   post.md5 #=> String
     # @return [String] MD5 checksum associated with this post
     attr_reader :md5
 
+    # Image of post
+    # @example Get post's image
+    #   post.image #=> E621::Image
     # @return [E621::Image] file content of this post
     attr_reader :image
 
+    # Sample of post
+    # @example Get post's image
+    #   post.sample #=> E621::Sample
     # @return [E621::Sample] sample data in E621::Sample format
     attr_reader :sample
 
+    # Preview of post
+    # @example Get post's image
+    #   post.preview #=> E621::Preview
     # @return [E621::Preview] preview data in E621::Preview format
     attr_reader :preview
 
+    # Deletion reason of post, if any
+    # @example Get deletion reason of post
+    #   post.delreason #=> String or nil
     # @return [String|NilClass] reason for deletion, if deleted
     attr_reader :delreason
 
+    # Tags of post
+    # @example Get tags of post, without web interaction
+    #   post.tags #=> Array<E621::Tag>
     # @return [Array<E621::Tag>] tags of this post
     attr_reader :tags
 
     # @author Maxine Michalski
     #
-    # Initializer for Post.
+    # Initializer for Post
     #
     # @param post [Hash] post data
-    #
+    # @example Get new post instance
+    #   E621::Post.new(id: 1) #=> E621::Post instance
     # @return the object
     def initialize(post)
       raise ArgumentError, "#{post.class} is not a Hash" unless post.is_a?(Hash)
@@ -109,30 +166,45 @@ module Rubyhexagon
 
     # @author Maxine Michalski
     #
-    # Test status with an optional parameter. This is more meant to be used by
-    # alias methods
+    # Test status with an optional parameter
     #
     # @param test_var [Symbol] variable under test
-    #
-    # @return [TrueClass]
-    # @return [FalseClass]
+    # @api private
+    # @example Get rating status
+    #   post.explicit? #=> true or false
+    # @return [TrueClass|FalseClass]
     def test(test_var = nil)
       test_var ||= __callee__.to_s.sub(/\?/, '').to_sym
       test_ar = %i[safe questionable explicit]
       test_ar.include?(test_var) ? @rating == test_var : @status == test_var
     end
+    # @see test
+    # @api public
     alias active? test
+    # @api public
+    # @see test
     alias flagged? test
+    # @api public
+    # @see test
     alias pending? test
+    # @api public
+    # @see test
     alias deleted? test
+    # @api public
+    # @see test
     alias safe? test
+    # @api public
+    # @see test
     alias questionable? test
+    # @api public
+    # @see test
     alias explicit? test
 
     # @author Maxine Michalski
     #
     # Show if post has comments or not
-    #
+    # @example Get if post has comments
+    #   post.comments? #=> true or false
     # @return [TrueClass|FalseClass]
     def comments?
       return false if @has_comments.nil?
@@ -142,7 +214,8 @@ module Rubyhexagon
     # @author Maxine Michalski
     #
     # Show if post has a parent
-    #
+    # @example Has post a parent?
+    #   post.parent? #=> true or false
     # @return [TrueClass|FalseClass]
     def parent?
       !@parent.nil?
@@ -151,7 +224,8 @@ module Rubyhexagon
     # @author Maxine Michalski
     #
     # Show if post has children
-    #
+    # @example Has post children?
+    #   post.children? #=> true or false
     # @return [TrueClass|FalseClass]
     def children?
       return false if @has_children.nil?
@@ -161,7 +235,8 @@ module Rubyhexagon
     # @author Maxine Michalski
     #
     # Comparison method for posts
-    #
+    # @example Compare two unequal posts
+    #   Post.new(id: 1) == Post.new(id: 2) #=> false
     # @return [TrueClass, FalseClass]
     def ==(other)
       other.is_a?(Post) && @id == other.id
@@ -170,19 +245,36 @@ module Rubyhexagon
     # @author Maxine Michalski
     #
     # Has post notes?
-    #
-    # @return [TrueClass, FalseClass]
+    # @example Post has notes?
+    #   post.notes? #=> true or false
+    # @return [TrueClass|FalseClass]
     def notes?
       @has_notes
     end
 
+    # @author Maxine Michalski
+    #
+    # Turn object into a hash representation of itself
+    #
+    # @example Turn a User into a Hash
+    #   Tag.new(id: 1).to_hash #=> { id: 1 }
+    # @return [Hash]
+    def to_hash
+      hash = {}
+      instance_variables.each do |i|
+        hash.store(i.to_s.sub(/^@/, '').to_sym, instance_variable_get(i))
+      end
+      hash
+    end
+
     private
 
     # @author Maxine Michalski
     #
     # Set author information
-    #
+    # @api private
     # @param post [Hash] post data
+    # @return [E621::User]
     def setup_author(post)
       return if post[:creator_id].nil?
       @author = E621::User.new(id: post[:creator_id], name: post[:author])
@@ -191,8 +283,9 @@ module Rubyhexagon
     # @author Maxine Michalski
     #
     # Set rating for post
-    #
+    # @api private
     # @param rating [String] rating of this post
+    # @return [Symbol]
     def setup_rating(rating)
       @rating = case rating
                 when 's' then :safe
@@ -205,8 +298,10 @@ module Rubyhexagon
     #
     # Set creation time
     #
+    # @api private
     # @param time [Time] Hash that includes creation time in UNIX Epoch on an
-    # `:s` key.
+    # `:s` key
+    # @return [Time]
     def setup_created_at(time)
       @created_at = Time.at(time[:s]) unless time.nil?
     end
@@ -214,8 +309,9 @@ module Rubyhexagon
     # @author Maxine Michalski
     #
     # Set status of post
-    #
+    # @api private
     # @param status [String] Status of post
+    # @return [Symbol]
     def setup_status(status)
       @status = status.to_sym unless status.nil?
     end
@@ -223,8 +319,9 @@ module Rubyhexagon
     # @author Maxine Michalski
     #
     # Set sources of post
-    #
+    # @api private
     # @param sources [Array<String>] Sources of post
+    # @return [Array<String>]
     def setup_sources(sources)
       @sources = sources.nil? ? [] : sources
     end
@@ -234,9 +331,10 @@ module Rubyhexagon
     # Set parent post
     #
     # @param parent [Integer] Parent post ID
-    #
-    # @notice A parent post is only set with an ID and further information must
+    # @api private
+    # @note A parent post is only set with an ID and further information must
     # be fetched manually.
+    # @return [E621::Post|NilClass]
     def setup_parent_id(parent)
       @parent = parent.nil? ? nil : E621::Post.new(id: parent)
     end
@@ -246,9 +344,10 @@ module Rubyhexagon
     # Set children posts
     #
     # @param children [Array<Integer>] Children post IDs
-    #
-    # @notice All children are only set with an ID and further information must
+    # @api private
+    # @note All children are only set with an ID and further information must
     # be fetched manually.
+    # @return [Array<E621::Post>]
     def setup_children(children)
       return [] if children.nil?
       @children = children.split(',').map { |c| E621::Post.new(id: c) }
@@ -259,20 +358,41 @@ module Rubyhexagon
     # Set post description
     #
     # @param description [String] Post description
-    #
-    # @notice Empty descriptions are set to nil
+    # @api private
+    # @note Empty descriptions are set to nil
+    # @return [String|NilClass]
     def setup_description(description)
       @description = !description.nil? && description.empty? ? nil : description
     end
 
+    # @author Maxine Michalski
+    #
+    # Setup artist for post
+    #
+    # @param artists [Array<String>] array of artist names
+    # @api private
+    # @return [Array<E621::Artist>]
     def setup_artist(artists)
       @artists = artists.map { |a| E621::Artist.new(name: CGI.unescape(a)) }
     end
 
+    # @author Maxine Michalski
+    #
+    # Setup tags for post
+    # @param tags [String] String that contains tags, separated by spaces
+    # @api private
+    # @note These tags can only be read by #tags
+    # @return [Array<E621::Tag>
     def setup_tags(tags)
       @tags = tags.split(' ').map { |t| E621::Tag.new(name: t) }
     end
 
+    # @author Maxine Michalski
+    #
+    # Setup files for posts
+    # @param post [Hash] post data
+    # @api private
+    # @return [E621::Post::Image|E621::Post::Sample|E621::Post::Preview]
     def setup_files(post)
       return if post[:file_url].nil?
       @image = Image.new(url: post[:file_url], ext: post[:file_ext],