lib/picturehouse_uk/cinema.rb in picturehouse_uk-1.0.0 vs lib/picturehouse_uk/cinema.rb in picturehouse_uk-1.0.1

@@ -1,86 +1,72 @@
 module PicturehouseUk
 
-  # Public: The object representing a cinema on the Picturehouse UK website
+  # The object representing a cinema on the Picturehouse UK website
   class Cinema
 
-    # Public: Returns the String brand of the cinema #=> 'Picturehouse'
+    # @return [String] the brand of the cinema
     attr_reader :brand
-    # Public: Returns the String id of the cinema on the Picturehouse website
+    # @return [String] the id of the cinema on the Picturehouse website
     attr_reader :id
-    # Public: Returns the String name of the cinema
+    # @return [String] the name of the cinema
     attr_reader :name
-    # Public: Returns the String slug of the cinema
+    # @return [String] the slug of the cinema
     attr_reader :slug
-    # Public: Returns the String url of the cinema's page on picturehouses.co.uk
+    # @return [String] the url of the cinema on the Picturehouse website
     attr_reader :url
 
-    # Public: Initialize a cinema
-    #
-    # id   - String of the cinema on the picturehouse website
-    # name - String of cinema name
-    # url  - String of cinema url on the picturehouse website
+    # @param [String] id cinema id from the site
+    # @param [String] name cinema name
+    # @param [String] url url on Picturehouse website
+    # @return [PicturehouseUk::Cinema]
     def initialize(id, name, url)
       @brand = 'Picturehouse'
       @id    = id
       @name  = name
       @slug  = name.downcase.gsub(/[^0-9a-z ]/,'').gsub(/\s+/, '-')
       @url   = (url[0] == '/') ? "http://www.picturehouses.co.uk#{url}" : url
     end
 
-    # Public: Return basic cinema information for all Picturehouse cinemas
-    #
-    # Examples
-    #
+    # Return basic cinema information for all cinemas
+    # @return [Array<PicturehouseUk::Cinema>]
+    # @example
     #   PicturehouseUk::Cinema.all
     #   # => [<PicturehouseUK::Cinema brand="Picturehouse" name="Duke's At Komedia" slug="dukes-at-komedia" id="Dukes_At_Komedia" url="...">, #=> <PicturehouseUK::Cinema brand="Picturehouse" name="Duke o York's" slug="duke-of-yorks" id="Duke_Of_Yorks" url="...">, ...]
-    #
-    # Returns an array of hashes of cinema information.
     def self.all
       cinema_links.map do |link|
         new_from_link link
       end
     end
 
-    # Public: Return single cinema information for an Odeon cinema
-    #
-    # string - a string representing the cinema id
-    #
-    # Examples
-    #
+    # Find a single cinema
+    # @param [String] id the cinema id as used on the picturehouses.co.uk website
+    # @return [PicturehouseUk::Cinema, nil]
+    # @example
     #   PicturehouseUk::Cinema.find('Dukes_At_Komedia')
     #   # => <PicturehouseUK::Cinema brand="Picturehouse" name="Duke's At Komedia" slug="dukes-at-komedia" id="Dukes_At_Komedia" url="...">
-    #
-    # Returns an PicturehouseUk::Cinema or nil if none was found
     def self.find(id)
       all.select { |cinema| cinema.id == id }[0]
     end
 
-    # Public: Returns films for an Picturehouse cinema
-    #
-    # Examples
-    #
+    # Films with showings scheduled at this cinema
+    # @return [Array<PicturehouseUk::Film>]
+    # @example
     #   cinema = PicturehouseUk::Cinema.find('Dukes_At_Komedia')
     #   cinema.films
     #   # => [<PicturehouseUk::Film name="Iron Man 3">, <PicturehouseUk::Film name="Star Trek Into Darkness">]
-    #
-    # Returns an array of PicturehouseUk::Film objects
     def films
       film_nodes.map do |node|
         parser = PicturehouseUk::Internal::FilmWithScreeningsParser.new node.to_s
         PicturehouseUk::Film.new parser.film_name
       end.uniq
     end
 
-    # Public: Returns screenings for a Picturehouse cinema
-    #
-    # Examples
-    #
+    # All planned screenings
+    # @return [Array<PicturehouseUk::Screening>]
+    # @example
     #   cinema = PicturehouseUk::Cinema.find('Dukes_At_Komedia')
     #   cinema.screenings
     #   # => [<PicturehouseUk::Screening film_name="Iron Man 3" cinema_name="Duke's At Komedia" when="..." varient="...">, <PicturehouseUk::Screening ...>]
-    #
-    # Returns an array of Odeon::Screening objects
     def screenings
       film_nodes.map do |node|
         parser = PicturehouseUk::Internal::FilmWithScreeningsParser.new node.to_s
         parser.showings.map do |screening_type, times|
           times.map do |time|