From 713e4286d7200ddba7954b859472f623cb7f13dc Mon Sep 17 00:00:00 2001 From: TOMITA Masahiro Date: Sun, 14 Nov 2021 21:35:22 +0900 Subject: [PATCH] YARD --- lib/mysql.rb | 41 +++++++++++------- lib/mysql/protocol.rb | 97 +++++++++++++++---------------------------- 2 files changed, 59 insertions(+), 79 deletions(-) diff --git a/lib/mysql.rb b/lib/mysql.rb index ab8e629..d2a1fdd 100644 --- a/lib/mysql.rb +++ b/lib/mysql.rb @@ -75,7 +75,16 @@ def escape_string(str) # @overload initialize(uri, **opts) # @param uri [String, URI] "mysql://username:password@host:port/database?param=value&..." / "mysql://username:password@%2Ftmp%2Fmysql.sock/database" / "mysql://username:password@/database?socket=/tmp/mysql.sock" + # @param opts [Hash] options # @overload initialize(host, username, password, database, port, socket, flags, **opts) + # @param host [String] hostname mysqld running + # @param username [String] username to connect to mysqld + # @param password [String] password to connect to mysqld + # @param database [String] initial database name + # @param port [String] port number (used if host is not 'localhost' or nil) + # @param socket [String] socket filename (used if host is 'localhost' or nil) + # @param flags [Integer] connection flag. Mysql::CLIENT_* ORed + # @param opts [Hash] options # @overload initialize(host: nil, username: nil, password: nil, database: nil, port: nil, socket: nil, flags: nil, **opts) # @param host [String] hostname mysqld running # @param username [String] username to connect to mysqld @@ -85,21 +94,21 @@ def escape_string(str) # @param socket [String] socket filename (used if host is 'localhost' or nil) # @param flags [Integer] connection flag. Mysql::CLIENT_* ORed # @param opts [Hash] options - # @option :host [String] hostname mysqld running - # @option :username [String] username to connect to mysqld - # @option :password [String] password to connect to mysqld - # @option :database [String] initial database name - # @option :port [String] port number (used if host is not 'localhost' or nil) - # @option :socket [String] socket filename (used if host is 'localhost' or nil) - # @option :flags [Integer] connection flag. Mysql::CLIENT_* ORed - # @option :charset [Mysql::Charset, String] character set - # @option :connect_timeout [Numeric, nil] - # @option :read_timeout [Numeric, nil] - # @option :write_timeout [Numeric, nil] - # @option :local_infile [Boolean] - # @option :load_data_local_dir [String] - # @option :ssl_mode [Integer] - # @option :get_server_public_key [Boolean] + # @option opts :host [String] hostname mysqld running + # @option opts :username [String] username to connect to mysqld + # @option opts :password [String] password to connect to mysqld + # @option opts :database [String] initial database name + # @option opts :port [String] port number (used if host is not 'localhost' or nil) + # @option opts :socket [String] socket filename (used if host is 'localhost' or nil) + # @option opts :flags [Integer] connection flag. Mysql::CLIENT_* ORed + # @option opts :charset [Mysql::Charset, String] character set + # @option opts :connect_timeout [Numeric, nil] + # @option opts :read_timeout [Numeric, nil] + # @option opts :write_timeout [Numeric, nil] + # @option opts :local_infile [Boolean] + # @option opts :load_data_local_dir [String] + # @option opts :ssl_mode [Integer] + # @option opts :get_server_public_key [Boolean] def initialize(*args, **opts) @fields = nil @protocol = nil @@ -209,7 +218,7 @@ def charset end # Set charset of MySQL connection. - # @param [String / Mysql::Charset] cs + # @param [String, Mysql::Charset] cs def charset=(cs) charset = cs.is_a?(Charset) ? cs : Charset.by_name(cs) if @protocol diff --git a/lib/mysql/protocol.rb b/lib/mysql/protocol.rb index 272716f..20eab62 100644 --- a/lib/mysql/protocol.rb +++ b/lib/mysql/protocol.rb @@ -15,12 +15,10 @@ class Protocol MAX_PACKET_LENGTH = 2**24-1 # Convert netdata to Ruby value - # === Argument - # data :: [Packet] packet data - # type :: [Integer] field type - # unsigned :: [true or false] true if value is unsigned - # === Return - # Object :: converted value. + # @param data [Packet] packet data + # @param type [Integer] field type + # @param unsigned [true or false] true if value is unsigned + # @return [Object] converted value. def self.net2value(pkt, type, unsigned) case type when Field::TYPE_STRING, Field::TYPE_VAR_STRING, Field::TYPE_NEWDECIMAL, Field::TYPE_BLOB, Field::TYPE_JSON @@ -67,13 +65,10 @@ def self.net2value(pkt, type, unsigned) end # convert Ruby value to netdata - # === Argument - # v :: [Object] Ruby value. - # === Return - # Integer :: type of column. Field::TYPE_* - # String :: netdata - # === Exception - # ProtocolError :: value too large / value is not supported + # @param v [Object] Ruby value. + # @return [Integer] type of column. Field::TYPE_* + # @return [String] netdata + # @raise [ProtocolError] value too large / value is not supported def self.value2net(v) case v when nil @@ -232,10 +227,8 @@ def quit_command end # Query command - # === Argument - # query :: [String] query string - # === Return - # [Integer / nil] number of fields of results. nil if no results. + # @param query [String] query string + # @return [Integer, nil] number of fields of results. nil if no results. def query_command(query) check_state :READY begin @@ -249,8 +242,7 @@ def query_command(query) end # get result of query. - # === Return - # [integer / nil] number of fields of results. nil if no results. + # @return [integer, nil] number of fields of results. nil if no results. def get_result begin res_packet = ResultPacket.parse read @@ -285,10 +277,8 @@ def send_local_file(filename) end # Retrieve n fields - # === Argument - # n :: [Integer] number of fields - # === Return - # [Array of Mysql::Field] field list + # @param n [Integer] number of fields + # @return [Array] field list def retr_fields(n) check_state :FIELD begin @@ -303,10 +293,8 @@ def retr_fields(n) end # Retrieve all records for simple query - # === Argument - # fields :: [Array] number of fields - # === Return - # [Array of Array of String] all records + # @param fields [Array] number of fields + # @return [Array>] all records def retr_all_records(fields) check_state :RESULT enc = charset.encoding @@ -354,12 +342,8 @@ def statistics_command end # Stmt prepare command - # === Argument - # stmt :: [String] prepared statement - # === Return - # [Integer] statement id - # [Integer] number of parameters - # [Array of Field] field list + # @param stmt [String] prepared statement + # @return [Array>] statement id, number of parameters, field list def stmt_prepare_command(stmt) synchronize do reset @@ -380,11 +364,9 @@ def stmt_prepare_command(stmt) end # Stmt execute command - # === Argument - # stmt_id :: [Integer] statement id - # values :: [Array] parameters - # === Return - # [Integer] number of fields + # @param stmt_id [Integer] statement id + # @param values [Array] parameters + # @return [Integer] number of fields def stmt_execute_command(stmt_id, values) check_state :READY begin @@ -398,11 +380,9 @@ def stmt_execute_command(stmt_id, values) end # Retrieve all records for prepared statement - # === Argument - # fields :: [Array of Mysql::Fields] field list - # charset :: [Mysql::Charset] - # === Return - # [Array of Array of Object] all records + # @param fields [Array of Mysql::Fields] field list + # @param charset [Mysql::Charset] + # @return [Array>] all records def stmt_retr_all_records(fields, charset) check_state :RESULT enc = charset.encoding @@ -418,8 +398,7 @@ def stmt_retr_all_records(fields, charset) end # Stmt close command - # === Argument - # stmt_id :: [Integer] statement id + # @param stmt_id [Integer] statement id def stmt_close_command(stmt_id) synchronize do reset @@ -465,10 +444,8 @@ def reset end # Read one packet data - # === Return - # [Packet] packet data - # === Exception - # [ProtocolError] invalid packet sequence number + # @return [Packet] packet data + # @rails [ProtocolError] invalid packet sequence number def read data = '' len = nil @@ -529,8 +506,7 @@ def read_timeout(len, timeout) end # Write one packet data - # === Argument - # data :: [String / IO] packet data. If data is nil, write empty packet. + # @param data [String, IO, nil] packet data. If data is nil, write empty packet. def write(data) begin @socket.sync = false @@ -574,17 +550,14 @@ def write_timeout(data, timeout) end # Read EOF packet - # === Exception - # [ProtocolError] packet is not EOF + # @raise [ProtocolError] packet is not EOF def read_eof_packet raise ProtocolError, "packet is not EOF" unless read.eof? end # Send simple command - # === Argument - # packet :: [String] packet data - # === Return - # [String] received data + # @param packet :: [String] packet data + # @return [String] received data def simple_command(packet) synchronize do reset @@ -794,17 +767,15 @@ def to_a end class StmtRawRecord - # === Argument - # pkt :: [Packet] - # fields :: [Array of Fields] - # encoding:: [Encoding] + # @param pkt [Packet] + # @param fields [Array of Fields] + # @param encoding [Encoding] def initialize(packet, fields, encoding) @packet, @fields, @encoding = packet, fields, encoding end # Parse statement result packet - # === Return - # [Array of Object] one record + # @return [Array] one record def parse_record_packet @packet.utiny # skip first byte null_bit_map = @packet.read((@fields.length+7+2)/8).unpack("b*").first