From 652484598d802cd808b4b1fe4bef263b53e3119c Mon Sep 17 00:00:00 2001 From: akr Date: Mon, 22 Mar 2010 09:45:57 +0000 Subject: update doc. git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@27012 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- ext/socket/ancdata.c | 4 ++++ ext/socket/basicsocket.c | 29 ++++++++++++++++++++--------- ext/socket/ipsocket.c | 2 +- ext/socket/lib/socket.rb | 2 +- ext/socket/option.c | 8 ++++++-- ext/socket/socket.c | 43 +++++++++++++++++++++++++------------------ ext/socket/tcpserver.c | 2 +- ext/socket/tcpsocket.c | 2 +- ext/socket/udpsocket.c | 2 +- ext/socket/unixserver.c | 2 +- ext/socket/unixsocket.c | 2 +- 11 files changed, 62 insertions(+), 36 deletions(-) (limited to 'ext/socket') diff --git a/ext/socket/ancdata.c b/ext/socket/ancdata.c index 11409aa834..0d3846056a 100644 --- a/ext/socket/ancdata.c +++ b/ext/socket/ancdata.c @@ -1769,6 +1769,10 @@ rsock_bsock_recvmsg_nonblock(int argc, VALUE *argv, VALUE sock) /* * Document-class: ::Socket::AncillaryData + * + * Socket::AncillaryData represents the ancillary data (control information) + * used by sendmsg and recvmsg system call. + * It contains socket family, cmsg level, cmsg type and cmsg data. */ void Init_ancdata(void) diff --git a/ext/socket/basicsocket.c b/ext/socket/basicsocket.c index 5e28bcf956..60db31074c 100644 --- a/ext/socket/basicsocket.c +++ b/ext/socket/basicsocket.c @@ -89,7 +89,7 @@ bsock_shutdown(int argc, VALUE *argv, VALUE sock) * call-seq: * basicsocket.close_read => nil * - * Disallows further read. + * Disallows further read using shutdown system call. * * s1, s2 = UNIXSocket.pair * s1.close_read @@ -117,7 +117,7 @@ bsock_close_read(VALUE sock) * call-seq: * basicsocket.close_write => nil * - * Disallows further write. + * Disallows further write using shutdown system call. * * UNIXSocket.pair {|s1, s2| * s1.print "ping" @@ -198,7 +198,8 @@ bsock_close_write(VALUE sock) * }; * * In this case #setsockopt could be called like this: - * optval = IPAddr.new("224.0.0.251").hton + IPAddr.new(Socket::INADDR_ANY, Socket::AF_INET).hton + * optval = IPAddr.new("224.0.0.251").hton + + * IPAddr.new(Socket::INADDR_ANY, Socket::AF_INET).hton * sock.setsockopt(Socket::IPPROTO_IP, Socket::IP_ADD_MEMBERSHIP, optval) * */ @@ -263,7 +264,7 @@ bsock_setsockopt(int argc, VALUE *argv, VALUE sock) * * Gets a socket option. These are protocol and system specific, see your * local system documentation for details. The option is returned as - * a Socket::Option. + * a Socket::Option object. * * === Parameters * * +level+ is an integer, usually one of the SOL_ constants such as @@ -349,7 +350,8 @@ bsock_getsockopt(VALUE sock, VALUE lev, VALUE optname) * p serv.getsockname #=> "\x02\x00;\x10\x7F\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00\x00" * } * - * If Addrinfo object is preferred, use BasicSocket#local_address. + * If Addrinfo object is preferred over the binary string, + * use BasicSocket#local_address. */ static VALUE bsock_getsockname(VALUE sock) @@ -376,7 +378,8 @@ bsock_getsockname(VALUE sock) * p s.getpeername #=> "\x02\x00\x82u\x7F\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00\x00" * } * - * If Addrinfo object is preferred, use BasicSocket#remote_address. + * If Addrinfo object is preferred over the binary string, + * use BasicSocket#remote_address. * */ static VALUE @@ -458,6 +461,10 @@ bsock_getpeereid(VALUE self) * * Note that addrinfo.protocol is filled by 0. * + * TCPSocket.open("www.ruby-lang.org", 80) {|s| + * p s.local_address #=> # + * } + * * TCPServer.open("127.0.0.1", 1512) {|serv| * p serv.local_address #=> # * } @@ -484,6 +491,10 @@ bsock_local_address(VALUE sock) * * Note that addrinfo.protocol is filled by 0. * + * TCPSocket.open("www.ruby-lang.org", 80) {|s| + * p s.remote_address #=> # + * } + * * TCPServer.open("127.0.0.1", 1728) {|serv| * c = TCPSocket.new("127.0.0.1", 1728) * s = serv.accept @@ -506,7 +517,7 @@ bsock_remote_address(VALUE sock) /* * call-seq: - * basicsocket.send(mesg, flags [, sockaddr_to]) => numbytes_sent + * basicsocket.send(mesg, flags [, dest_sockaddr]) => numbytes_sent * * send _mesg_ via _basicsocket_. * @@ -514,7 +525,7 @@ bsock_remote_address(VALUE sock) * * _flags_ should be a bitwise OR of Socket::MSG_* constants. * - * _sockaddr_to_ should be a packed sockaddr string or an addrinfo. + * _dest_sockaddr_ should be a packed sockaddr string or an addrinfo. * * TCPSocket.open("localhost", 80) {|s| * s.send "GET / HTTP/1.0\r\n\r\n", 0 @@ -722,7 +733,7 @@ bsock_do_not_rev_lookup_set(VALUE self, VALUE val) } /* - * BasicSocket class + * BasicSocket is the super class for the all socket classes. */ void Init_basicsocket(void) diff --git a/ext/socket/ipsocket.c b/ext/socket/ipsocket.c index ad1ac231c3..c1f329b52e 100644 --- a/ext/socket/ipsocket.c +++ b/ext/socket/ipsocket.c @@ -286,7 +286,7 @@ ip_s_getaddress(VALUE obj, VALUE host) /* * Document-class: ::IPSocket < BasicSocket * - * IPSocket class + * IPSocket is the super class of TCPSocket and UDPSocket. */ void Init_ipsocket(void) diff --git a/ext/socket/lib/socket.rb b/ext/socket/lib/socket.rb index 5b7438182d..0f26c3efc5 100644 --- a/ext/socket/lib/socket.rb +++ b/ext/socket/lib/socket.rb @@ -683,7 +683,7 @@ class Socket < BasicSocket end end - # creates UNIX server sockets on _path_ + # creates a UNIX server socket on _path_ # # If no block given, it returns a listening socket. # diff --git a/ext/socket/option.c b/ext/socket/option.c index 89265b78ad..4be651f7c6 100644 --- a/ext/socket/option.c +++ b/ext/socket/option.c @@ -148,7 +148,7 @@ sockopt_data(VALUE self) * * Creates a new Socket::Option object which contains an int as data. * - * The size and endian is dependent on the host. + * The size and endian is dependent on the platform. * * p Socket::Option.int(:INET, :SOCKET, :KEEPALIVE, 1) * #=> # @@ -169,7 +169,7 @@ sockopt_s_int(VALUE klass, VALUE vfamily, VALUE vlevel, VALUE voptname, VALUE vi * * Returns the data in _sockopt_ as an int. * - * The size and endian is dependent on the host. + * The size and endian is dependent on the platform. * * sockopt = Socket::Option.int(:INET, :SOCKET, :KEEPALIVE, 1) * p sockopt.int => 1 @@ -660,6 +660,10 @@ sockopt_unpack(VALUE self, VALUE template) /* * Document-class: ::Socket::Option + * + * Socket::Option represents a socket option used by getsockopt and setsockopt + * system call. + * It contains socket family, protocol level, option name and option value. */ void Init_sockopt(void) diff --git a/ext/socket/socket.c b/ext/socket/socket.c index 1b026a6741..66dd5d9c20 100644 --- a/ext/socket/socket.c +++ b/ext/socket/socket.c @@ -134,13 +134,13 @@ rsock_sock_s_socketpair(int argc, VALUE *argv, VALUE klass) /* * call-seq: - * socket.connect(server_sockaddr) => 0 + * socket.connect(remote_sockaddr) => 0 * - * Requests a connection to be made on the given +server_sockaddr+. Returns 0 if + * Requests a connection to be made on the given +remote_sockaddr+. Returns 0 if * successful, otherwise an exception is raised. * * === Parameter - * * +server_sockaddr+ - the +struct+ sockaddr contained in a string + * * +remote_sockaddr+ - the +struct+ sockaddr contained in a string or Addrinfo object * * === Example: * # Pull down Google's web page @@ -263,14 +263,14 @@ sock_connect(VALUE sock, VALUE addr) /* * call-seq: - * socket.connect_nonblock(server_sockaddr) => 0 + * socket.connect_nonblock(remote_sockaddr) => 0 * - * Requests a connection to be made on the given +server_sockaddr+ after + * Requests a connection to be made on the given +remote_sockaddr+ after * O_NONBLOCK is set for the underlying file descriptor. * Returns 0 if successful, otherwise an exception is raised. * * === Parameter - * * +server_sockaddr+ - the +struct+ sockaddr contained in a string + * * +remote_sockaddr+ - the +struct+ sockaddr contained in a string or Addrinfo object * * === Example: * # Pull down Google's web page @@ -325,15 +325,22 @@ sock_connect_nonblock(VALUE sock, VALUE addr) /* * call-seq: - * socket.bind(server_sockaddr) => 0 + * socket.bind(local_sockaddr) => 0 * - * Binds to the given +struct+ sockaddr. + * Binds to the given local address. * * === Parameter - * * +server_sockaddr+ - the +struct+ sockaddr contained in a string + * * +local_sockaddr+ - the +struct+ sockaddr contained in a string or an Addrinfo object * * === Example * require 'socket' + * + * # use Addrinfo + * socket = Socket.new(:INET, :STREAM, 0) + * socket.bind(Addrinfo.tcp("127.0.0.1", 2222)) + * p socket.local_address #=> # + * + * # use struct sockaddr * include Socket::Constants * socket = Socket.new( AF_INET, SOCK_STREAM, 0 ) * sockaddr = Socket.pack_sockaddr_in( 2200, 'localhost' ) @@ -507,11 +514,11 @@ rsock_sock_listen(VALUE sock, VALUE log) * * Receives up to _maxlen_ bytes from +socket+. _flags_ is zero or more * of the +MSG_+ options. The first element of the results, _mesg_, is the data - * received. The second element, _sender_addrinfo_, contains protocol-specific information - * on the sender. + * received. The second element, _sender_addrinfo_, contains protocol-specific + * address information of the sender. * * === Parameters - * * +maxlen+ - the number of bytes to receive from the socket + * * +maxlen+ - the maximum number of bytes to receive from the socket * * +flags+ - zero or more of the +MSG_+ options * * === Example @@ -620,15 +627,15 @@ sock_recvfrom(int argc, VALUE *argv, VALUE sock) * O_NONBLOCK is set for the underlying file descriptor. * _flags_ is zero or more of the +MSG_+ options. * The first element of the results, _mesg_, is the data received. - * The second element, _sender_addrinfo_, contains protocol-specific information - * on the sender. + * The second element, _sender_addrinfo_, contains protocol-specific address + * information of the sender. * * When recvfrom(2) returns 0, Socket#recvfrom_nonblock returns * an empty string as data. * The meaning depends on the socket: EOF on TCP, empty packet on UDP, etc. * * === Parameters - * * +maxlen+ - the number of bytes to receive from the socket + * * +maxlen+ - the maximum number of bytes to receive from the socket * * +flags+ - zero or more of the +MSG_+ options * * === Example @@ -689,7 +696,7 @@ sock_recvfrom_nonblock(int argc, VALUE *argv, VALUE sock) * serv = Socket.new(:INET, :STREAM, 0) * serv.listen(5) * c = Socket.new(:INET, :STREAM, 0) - * c.connect(serv.local_address) + * c.connect(serv.connect_address) * p serv.accept #=> [#, #] * */ @@ -830,10 +837,10 @@ sock_sysaccept(VALUE sock) * * Returns the hostname. * - * Note that it is not guaranteed to be able to convert to IP address using gethostbyname, getaddrinfo, etc. - * * p Socket.gethostname #=> "hal" * + * Note that it is not guaranteed to be able to convert to IP address using gethostbyname, getaddrinfo, etc. + * If you need local IP address, use Socket.ip_address_list. */ static VALUE sock_gethostname(VALUE obj) diff --git a/ext/socket/tcpserver.c b/ext/socket/tcpserver.c index 229c2b1607..bd5701f6d2 100644 --- a/ext/socket/tcpserver.c +++ b/ext/socket/tcpserver.c @@ -131,7 +131,7 @@ tcp_sysaccept(VALUE sock) /* * Document-class: ::TCPServer < TCPSocket * - * TCPServer class + * TCPServer represents a TCP/IP server socket. */ void Init_tcpserver(void) diff --git a/ext/socket/tcpsocket.c b/ext/socket/tcpsocket.c index d7164ad861..fb51a01c97 100644 --- a/ext/socket/tcpsocket.c +++ b/ext/socket/tcpsocket.c @@ -58,7 +58,7 @@ tcp_s_gethostbyname(VALUE obj, VALUE host) /* * Document-class: ::TCPSocket < IPSocket * - * TCPSocket class + * TCPSocket represents a TCP/IP client socket. */ void Init_tcpsocket(void) diff --git a/ext/socket/udpsocket.c b/ext/socket/udpsocket.c index 3a42e0e25b..12b910d777 100644 --- a/ext/socket/udpsocket.c +++ b/ext/socket/udpsocket.c @@ -249,7 +249,7 @@ udp_recvfrom_nonblock(int argc, VALUE *argv, VALUE sock) /* * Document-class: ::UDPSocket < IPSocket * - * UDPSocket class + * UDPSocket represents a UDP/IP socket. */ void Init_udpsocket(void) diff --git a/ext/socket/unixserver.c b/ext/socket/unixserver.c index e29e9cb87b..86447e8aba 100644 --- a/ext/socket/unixserver.c +++ b/ext/socket/unixserver.c @@ -138,7 +138,7 @@ unix_sysaccept(VALUE sock) /* * Document-class: ::UNIXServer < UNIXSocket * - * UNIXServer class + * UNIXServer represents a UNIX domain stream server socket. */ void Init_unixserver(void) diff --git a/ext/socket/unixsocket.c b/ext/socket/unixsocket.c index 89beb666ec..8eca0d56c8 100644 --- a/ext/socket/unixsocket.c +++ b/ext/socket/unixsocket.c @@ -487,7 +487,7 @@ unix_s_socketpair(int argc, VALUE *argv, VALUE klass) /* * Document-class: ::UNIXSocket < BasicSocket * - * UNIXSocket class + * UNIXSocket represents a UNIX domain stream client socket. */ void Init_unixsocket(void) -- cgit v1.2.3