Started documentation with Yard

.gitignore

@@ -5,3 +5,5 @@ nbproject*
 .loadpath
 .rspec
 pkg/
+.yardoc/
+doc/

lib/stargate/operation/meta_operation.rb

@@ -1,20 +1,31 @@
 module Stargate
   module Operation
     module MetaOperation
+
+      # Get a list of tables
+      #
+      # @return [Array<Model::TableDescriptor>] array of TableDescriptor
       def list_tables
         request = Request::MetaRequest.new
         Response::MetaResponse.new(rest_get(request.list_tables), :list_tables).parse
       end
 
+      # Get the version string of the REST server
+      #
+      # @return [String] version number
       def version
         request = Request::MetaRequest.new
         rest_get(request.version, {"Accept" => "text/plain"}).strip
       end
 
+      # Get the version of the HBase cluster
+      #
+      # @return [String] cluster version number
       def cluster_version
         request = Request::MetaRequest.new
         rest_get(request.cluster_version, {"Accept" => "text/plain"}).strip
       end
+
     end
   end
 end

lib/stargate/operation/row_operation.rb

@@ -4,6 +4,17 @@ module RowOperation
 
       CONVERTER = { '&' => '&amp;', '<' => '&lt;', '>' => '&gt;', "'" => '&apos;', '"' => '&quot;' }.freeze
 
+      # Add a row to HBase
+      #
+      # Example:
+      #  client = Stargate::Client.new("http://localhost:8080")
+      #  client.set("test-hbase-stargate", "row1", {"col1:cell1" => "value for column 1, cell 1", "col1:cell2" => "value 2"})
+      #
+      # @param [String] table_name The HBase table name
+      # @param [String] row The row id
+      # @param [Hash] columns hash consisting of the keys as column names and their corresponding values
+      # @param [Integer] timestamp optional timestamp argument. Can be any custom value (in seconds), but HBase uses the time since epoch.
+      # @return [true,false] true or false depending on whether the row was added successfully
       def set(table_name, row, columns, timestamp = nil)
         # Changing from Ruby epoch time (seconds) to Java epoch time (milliseconds)
         timestamp = timestamp*1000 unless timestamp.nil?
@@ -45,10 +56,37 @@ def multi_get(table_name, rows, options = {})
         end
       end
 
+      # Get a row from HBase
+      #
+      # Example:
+      #  client = Stargate::Client.new("http://localhost:8080")
+      #  client.get("test-hbase-stargate", "row1", :timestamp => 1321846232, :columns => ["col1:cell1"], :version => 3)
+      #
+      # @param [String] table_name The HBase table name
+      # @param [String] row The row id
+      # @param [Hash] options the options to retrieve the row with
+      # @option options [Integer] :timestamp A specific timestamp the rows should have
+      # @option options [Array<String>] :columns List of columns to get
+      # @option options [Integer] :versions The number of versions to get back
+      # @return [Model::Row] object corresponding to the requested row, or nil if it could not be found
       def get(table_name, row, options = {})
         multi_get(table_name, row, options)[row]
       end
 
+      # Get a row from HBase
+      #
+      # Example:
+      #  client = Stargate::Client.new("http://localhost:8080")
+      #  row = client.show_row("test-hbase-stargate", "row1", nil, nil, :version => 2)
+      #
+      # @deprecated Use the {#get} method instead
+      # @param [String] table_name The HBase table name
+      # @param [String] name The row id
+      # @param [Integer] timestamp optional timestamp
+      # @param [Array<String>] columns name of the columns to retrieve. Use nil to get them all.
+      # @param [Hash] options the options to retrieve the row with
+      # @option options [Integer] :versions The number of versions to get back
+      # @return [Model::Row] object corresponding to the requested row, or nil if it could not be found
       def show_row(table_name, name, timestamp = nil, columns = nil, options = {})
         handle_exception(table_name, name) do
           options[:version] ||= 1
@@ -68,6 +106,18 @@ def show_row(table_name, name, timestamp = nil, columns = nil, options = {})
         end
       end
 
+      # Add a row to HBase
+      #
+      # Example:
+      #  client = Stargate::Client.new("http://localhost:8080")
+      #  client.create_row("test-hbase-stargate", "row1", nil, [{ :name => "col1:cell1", :value => "row2-col1-cell1" }, { :name => "col1:cell2", :value => "row2-col1-cell2" }])
+      #
+      # @deprecated Use the {#set} method instead
+      # @param [String] table_name The HBase table name
+      # @param [String] name The row id
+      # @param [Integer] timestamp optional timestamp argument. Can be any custom value (in seconds), but HBase uses the time since epoch.
+      # @param [Hash, Array<Hash>] columns
+      # @return [true,false] true or false depending on whether the row was added successfully
       def create_row(table_name, name, timestamp = nil, columns = nil)
         # Changing from Ruby epoch time (seconds) to Java epoch time (milliseconds)
         timestamp = timestamp*1000 unless timestamp.nil?
@@ -101,6 +151,12 @@ def create_row(table_name, name, timestamp = nil, columns = nil)
         end
       end
 
+      # Delete a row in HBase
+      #
+      # @param [String] table_name The HBase table name
+      # @param [String] name The row id
+      # @param [Integer] timestamp optional timestamp value (deletes all timestamp if not specified)
+      # @param [Array<String>] optional list of specific columns to delete (deletes all columns if not specified)
       def delete_row(table_name, name, timestamp = nil, columns = nil)
         handle_exception(table_name, name) do
           request = Request::RowRequest.new(table_name, name, timestamp)

lib/stargate/operation/scanner_operation.rb

@@ -1,13 +1,17 @@
 module Stargate
   module Operation
     module ScannerOperation
-      # Trying to maintain some API stability for now
-      def open_scanner(table_name, columns, start_row, stop_row = nil, timestamp = nil)
-        warn "[DEPRECATION] This method is deprecated. Use #open_scanner(table_name, options = {}) instead."
-
-        open_scanner(table_name, {:columns => columns, :start_row => start_row, :stop_row => stop_row, :timestamp => timestamp})
-      end
 
+      # Create a scanner for the given table along with options defined in the {Model::Scanner::AVAILABLE_OPTS} hash.
+      #
+      # Example:
+      #  client = Stargate::Client.new("http://localhost:8080")
+      #  scanner = client.open_scanner("test-hbase-stargate", :batch_size => 1000, :start_row => "row1", :end_row => "row2")
+      #
+      # @see Model::Scanner::AVAILABLE_OPTS
+      # @param [String] table_name the table name
+      # @param [Hash] options options for the scanner
+      # @return [Model::Scanner] object representing the scanner
       def open_scanner(table_name, options = {})
         raise ArgumentError, "options should be given as a Hash" unless options.instance_of? Hash
         columns = options.delete(:columns)
@@ -50,6 +54,22 @@ def open_scanner(table_name, options = {})
         end
       end
 
+      # Execute a given block on each row returned by the {Model::Scanner}. This will only store
+      # a batch size (defined during scanner creation) number of records and keep requesting more
+      # until a break or limit is reached. This means that it's safe to run this method against
+      # the whole dataset (assuming that each row encountered isn't being stored elsewhere).
+      #
+      # Example:
+      #  client = Stargate::Client.new("http://localhost:8080")
+      #  scanner = client.open_scanner("test-hbase-stargate")
+      #  client.each_row(scanner) do |row|
+      #    puts row.name
+      #  end
+      #
+      # @see #open_scanner
+      # @see Model::Scanner
+      # @param [Model::Scanner] scanner Scanner object that was previously open
+      # @yield [Model::Row] code to run against each row
       def each_row(scanner, &block)
         begin
           request = Request::ScannerRequest.new(scanner.table_name)
@@ -77,6 +97,20 @@ def each_row(scanner, &block)
         end
       end
 
+      # Get a list of rows from a given {Model::Scanner} that was previously created by the {#open_scanner} method.
+      # If a limit is given, then this method will only retrieve that amount, otherwise it will keep getting
+      # rows until the scanner is exhausted (i.e. there no more records).
+      #
+      # Example:
+      #  client = Stargate::Client.new("http://localhost:8080")
+      #  scanner = client.open_scanner("test-hbase-stargate")
+      #  rows = client.get_rows(scanner, 10)
+      #
+      # @see #open_scanner
+      # @see Model::Scanner
+      # @param [Model::Scanner] scanner Scanner object that was previously open
+      # @param [Integer] limit return this maximum number of records, or return all if nil
+      # @return [Array<Model::Row>] list of row records
       def get_rows(scanner, limit = nil)
         rows = []
         each_row(scanner) do |row|
@@ -86,6 +120,19 @@ def get_rows(scanner, limit = nil)
         return rows
       end
 
+      # Close a {Model::Scanner} object
+      #
+      # Example:
+      #  client = Stargate::Client.new("http://localhost:8080")
+      #  scanner = client.open_scanner("test-hbase-stargate")
+      #  client.each_row(scanner) do |row|
+      #    puts row.name
+      #  end
+      #  client.close_scanner(scanner)
+      #
+      # @see #open_scanner
+      # @see Model::Scanner
+      # @param [Model::Scanner] scanner Scanner object that was previously open
       def close_scanner(scanner)
         begin
           request = Request::ScannerRequest.new(scanner.table_name)

lib/stargate/operation/table_operation.rb

@@ -1,6 +1,11 @@
 module Stargate
   module Operation
     module TableOperation
+
+      # Get the TableDescriptor object for the table of the given name
+      #
+      # @param [String] name the table name
+      # @return [Model::TableDescriptor] TableDescriptor object corresponding to the table
       def show_table(name)
         begin
           request = Request::TableRequest.new(name)
@@ -10,8 +15,29 @@ def show_table(name)
         end
       end
 
+      # Create a table in HBase. Pass in one or more arguments after the table name to configure the column families
+      # that should be created. The arguments can be a mix of String (no options) or a Hash with options specified
+      # from the key names of the {Model::ColumnDescriptor::AVAILABLE_OPTS} hash.
+      #
+      # Example:
+      #  client = Stargate::Client.new("http://localhost:8080")
+      #  table_options = { :name => 'columnfamily1',
+      #          :max_version => 3,
+      #          :compression => Stargate::Model::CompressionType::NONE,
+      #          :in_memory => false,
+      #          :block_cache => false,
+      #          :ttl => -1,
+      #          :max_cell_size => 2147483647,
+      #          :bloomfilter => false
+      #        }
+      #  client.create_table('test-hbase-stargate', table_options)
+      #
+      # @see Model::ColumnDescriptor::AVAILABLE_OPTS
+      # @param [String] name the table name
+      # @param [String, Hash] args initial column family
+      # @return [true,false] whether or not the table was created
       def create_table(name, *args)
-        raise StandardError, "Table name must be of type String" unless name.instance_of? String
+        raise ArgumentError, "Table name must be of type String" unless name.instance_of? String
 
         request = Request::TableRequest.new(name)
         begin
@@ -30,7 +56,7 @@ def create_table(name, *args)
 
               xml_data << "/>"
             else
-              raise StandardError, "#{arg.class.to_s} of #{arg.to_s} is not of Hash Type"
+              raise ArgumentError, "#{arg.class.to_s} of #{arg.to_s} is not of Hash Type"
             end
           end
           xml_data << "</TableSchema>"
@@ -41,6 +67,9 @@ def create_table(name, *args)
         end
       end
 
+      # Will alter the table of the given name. Not currently implemented.
+      #
+      # @param [String] name the table name
       def alter_table(name, *args)
         raise NotImplementedError, "Altering the table is not supported yet"
 
@@ -60,6 +89,10 @@ def alter_table(name, *args)
         end
       end
 
+      # Delete the table with the given name and optionally choose certain columns to delete
+      #
+      # @param [String] name the table name
+      # @param [Array<String>] [Deprecated] list of column names
       def delete_table(name, columns = nil)
         begin
           request = Request::TableRequest.new(name)
@@ -73,19 +106,15 @@ def delete_table(name, columns = nil)
         end
       end
 
+      # (see #delete_table)
       def destroy_table(name, columns = nil)
         delete_table(name, columns)
       end
 
-      def enable_table(name)
-        warn "[DEPRECATION] Explicitly enabling tables isn't required anymore. HBase Stargate will enable/disable as needed."
-      end
-
-      def disable_table(name)
-        warn "[DEPRECATION] Explicitly disabling tables isn't required anymore. HBase Stargate will enable/disable as needed."
-      end
-
+      # List of table regions
+      #
       def table_regions(name, start_row = nil, end_row = nil)
+        raise NotImplementedError, "Getting the table regions is not supported yet"
       end
 
     end