mysql: update documentation

vlib/mysql/mysql.v

@@ -17,7 +17,7 @@ pub mut:
 	flag     int
 }
 
-// connect Connects to a MySQL server
+// connect connects to a MySQL server.
 pub fn (mut conn Connection) connect() ?bool {
 	instance := C.mysql_init(conn.conn)
 	conn.conn = C.mysql_real_connect(
@@ -36,7 +36,8 @@ pub fn (mut conn Connection) connect() ?bool {
 	return true
 }
 
-// query Performs a query on the database
+// query executes an SQL query.
+// `query()` cannot be used for statements that contain binary data; you must use `real_query()` instead.
 pub fn (conn Connection) query(q string) ?Result {
 	if C.mysql_query(conn.conn, q.str) != 0 {
 		return error_with_code(get_error_msg(conn.conn), get_errno(conn.conn))
@@ -45,7 +46,19 @@ pub fn (conn Connection) query(q string) ?Result {
 	return Result{res}
 }
 
-// select_db Selects the default database for database queries
+// real_query executes an SQL query. Same as `query ()`,
+// But `real_query ()` can be used for statements containing binary data.
+// (Binary data may contain the \0 character, which `query()` interprets as the end of the statement string).
+// In addition, `real_query()` is faster than `query()`.
+pub fn (conn Connection) real_query(q string) ?Result {
+	if C.mysql_real_query(conn.conn, q.str, q.len) != 0 {
+		return error_with_code(get_error_msg(conn.conn), get_errno(conn.conn))
+	}
+	res := C.mysql_store_result(conn.conn)
+	return Result{res}
+}
+
+// select_db selects the default database for database queries.
 pub fn (conn Connection) select_db(dbname string) ?bool {
 	if C.mysql_select_db(conn.conn, dbname.str) != 0 {
 		return error_with_code(get_error_msg(conn.conn), get_errno(conn.conn))
@@ -53,9 +66,9 @@ pub fn (conn Connection) select_db(dbname string) ?bool {
 	return true
 }
 
-// change_user Changes the user of the specified database connection.
-// If desired, the empty string value can be passed to the `dbname` parameter
-// resulting in only changing the user and not selecting a database
+// change_user changes the user of the specified database connection.
+// if desired, the empty string value can be passed to the `dbname` parameter
+// resulting in only changing the user and not selecting a database.
 pub fn (conn Connection) change_user(username, password, dbname string) ?bool {
 	mut ret := true
 	if dbname != '' {
@@ -69,19 +82,19 @@ pub fn (conn Connection) change_user(username, password, dbname string) ?bool {
 	return ret
 }
 
-// affected_rows Returns the number of rows changed/deleted/inserted
-// by the last UPDATE, DELETE, or INSERT query
+// affected_rows returns the number of rows changed/deleted/inserted
+// by the last UPDATE, DELETE, or INSERT query.
 pub fn (conn Connection) affected_rows() u64 {
 	return C.mysql_affected_rows(conn.conn)
 }
 
-// autocommit Turns on or off auto-committing database modifications
+// autocommit turns on or off auto-committing database modifications.
 pub fn (conn Connection) autocommit(mode bool) {
 	C.mysql_autocommit(conn.conn, mode)
 }
 
-// tables Returns list of tables that match the `wildcard` parameter.
-// If empty string is passed, will return all tables
+// tables returns list of tables that match the `wildcard` parameter.
+// If empty string is passed, will return all tables.
 pub fn (conn Connection) tables(wildcard string) ?[]string {
 	cres := C.mysql_list_tables(conn.conn, wildcard.str)
 	if isnil(cres) {
@@ -96,7 +109,7 @@ pub fn (conn Connection) tables(wildcard string) ?[]string {
 	return tables
 }
 
-// escape_string Creates a legal SQL string for use in an SQL statement
+// escape_string creates a legal SQL string for use in an SQL statement.
 pub fn (conn Connection) escape_string(s string) string {
     len := C.strlen(s.str)
     to := malloc(2 * len + 1)
@@ -106,15 +119,15 @@ pub fn (conn Connection) escape_string(s string) string {
     return string(to)
 }
 
-// set_option Can be used to set extra connect options and affect behavior for a connection.
+// set_option is used to set extra connect options and affect behavior for a connection.
 // This function may be called multiple times to set several options.
-// To retrieve option values, use `get_option()`
+// To retrieve option values, use `get_option()`.
 pub fn (conn Connection) set_option(option_type int, val voidptr) {
 	C.mysql_options(conn.conn, option_type, val)
 }
 
-// get_option Returns the current value of an option settable `set_option`.
-// The value should be treated as read only
+// get_option returns the current value of an option settable `set_option`.
+// The value should be treated as read only.
 pub fn (conn Connection) get_option(option_type int) ?voidptr {
 	ret := voidptr(0)
 	if C.mysql_get_option(conn.conn, option_type, &ret) != 0 {
@@ -123,8 +136,8 @@ pub fn (conn Connection) get_option(option_type int) ?voidptr {
 	return ret
 }
 
-// refresh Flushes tables or caches, or resets replication server information.
-// The connected user must have the `RELOAD` privilege
+// refresh flushes tables or caches, or resets replication server information.
+// The connected user must have the `RELOAD` privilege.
 pub fn (conn Connection) refresh(options u32) ?bool {
 	if C.mysql_refresh(conn.conn, options) != 0 {
 		return error_with_code(get_error_msg(conn.conn), get_errno(conn.conn))
@@ -132,15 +145,15 @@ pub fn (conn Connection) refresh(options u32) ?bool {
 	return true
 }
 
-// reset_connection Resets the connection to clear the session state
-pub fn (conn Connection) reset_connection() ?bool {
+// reset resets the connection to clear the session state.
+pub fn (conn Connection) reset() ?bool {
 	if C.mysql_reset_connection(conn.conn) != 0 {
 		return error_with_code(get_error_msg(conn.conn), get_errno(conn.conn))
 	}
 	return true
 }
 
-// ping Pings a server connection, or tries to reconnect if the connection has gone down
+// ping pings a server connection, or tries to reconnect if the connection has gone down.
 pub fn (conn Connection) ping() ?bool {
 	if C.mysql_ping(conn.conn) != 0 {
 		return error_with_code(get_error_msg(conn.conn), get_errno(conn.conn))
@@ -148,48 +161,48 @@ pub fn (conn Connection) ping() ?bool {
 	return true
 }
 
-// close Closes a previously opened database connection
+// close closes a previously opened database connection.
 pub fn (conn &Connection) close() {
 	C.mysql_close(conn.conn)
 }
 
 /* -------------------------- MYSQL INFO & VERSION -------------------------- */
 
-// info Returns information about the most recently executed query
+// info returns information about the most recently executed query.
 pub fn (conn Connection) info() string {
 	return resolve_nil_str(C.mysql_info(conn.conn))
 }
 
-// get_host_info Returns a string describing the connection
+// get_host_info returns a string describing the connection.
 pub fn (conn Connection) get_host_info() string {
 	return string(C.mysql_get_host_info(conn.conn))
 }
 
-// get_server_info Returns the server version number as a string
+// get_server_info returns the server version number as a string.
 pub fn (conn Connection) get_server_info() string {
 	return string(C.mysql_get_server_info(conn.conn))
 }
 
-// get_server_version Returns the server version number as an integer
+// get_server_version returns the server version number as an integer.
 pub fn (conn Connection) get_server_version() u64 {
 	return C.mysql_get_server_version(conn.conn)
 }
 
 /* --------------------------------- CLIENT --------------------------------- */
 
-// get_client_info Returns client version information as a string
+// get_client_info returns client version information as a string.
 pub fn get_client_info() string {
 	return string(C.mysql_get_client_info())
 }
 
-// get_client_version Returns client version information as an integer
+// get_client_version returns client version information as an integer.
 pub fn get_client_version() u64 {
 	return C.mysql_get_client_version()
 }
 
 /* ------------------------------- MYSQL DEBUG ------------------------------ */
 
-// dump_debug_info Causes the server to write debug information to the log
+// dump_debug_info causes the server to write debug information to the log
 pub fn (conn Connection) dump_debug_info() ?bool {
 	if C.mysql_dump_debug_info(conn.conn) != 0 {
 		return error_with_code(get_error_msg(conn.conn), get_errno(conn.conn))
@@ -197,7 +210,7 @@ pub fn (conn Connection) dump_debug_info() ?bool {
 	return true
 }
 
-// debug Does a `DBUG_PUSH` with the given string.
+// debug does a `DBUG_PUSH` with the given string.
 // See https://dev.mysql.com/doc/refman/5.7/en/mysql-debug.html
 pub fn debug(debug string) {
 	C.mysql_debug(debug.str)