summaryrefslogtreecommitdiff
path: root/ext/socket/socket.c
diff options
context:
space:
mode:
authorzzak <zzak@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2012-10-20 03:51:33 +0000
committerzzak <zzak@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2012-10-20 03:51:33 +0000
commitf1e488e5241f52765550a7e5e20d1d7509da5b32 (patch)
treeeca70e8d7122dae5888b093e98524a14baae2c63 /ext/socket/socket.c
parentdd05478f2431dd734cfb3a1a858377497263aaa2 (diff)
* ext/socket/socket.c: Documentation for Socket
Based on a patch by David Albert [Bug #7105] [ruby-core:47828] git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@37274 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'ext/socket/socket.c')
-rw-r--r--ext/socket/socket.c81
1 files changed, 45 insertions, 36 deletions
diff --git a/ext/socket/socket.c b/ext/socket/socket.c
index 5a8bf07..09c22d6 100644
--- a/ext/socket/socket.c
+++ b/ext/socket/socket.c
@@ -27,9 +27,8 @@ setup_domain_and_type(VALUE domain, int *dv, VALUE type, int *tv)
*
* _socktype_ should be a socket type such as: :STREAM, :DGRAM, :RAW, etc.
*
- * _protocol_ should be a protocol defined in the domain.
- * This is optional.
- * If it is not given, 0 is used internally.
+ * _protocol_ is optional and should be a protocol defined in the domain.
+ * If protocol is not given, 0 is used internally.
*
* Socket.new(:INET, :STREAM) # TCP socket
* Socket.new(:INET, :DGRAM) # UDP socket
@@ -140,8 +139,8 @@ rsock_socketpair(int domain, int type, int protocol, int sv[2])
*
* _socktype_ should be a socket type such as: :STREAM, :DGRAM, :RAW, etc.
*
- * _protocol_ should be a protocol defined in the domain.
- * 0 is default protocol for the domain.
+ * _protocol_ should be a protocol defined in the domain,
+ * defaults to 0 for the domain.
*
* s1, s2 = Socket.pair(:UNIX, :DGRAM, 0)
* s1.send "a", 0
@@ -1134,8 +1133,8 @@ sock_s_getservbyport(int argc, VALUE *argv)
*
* _socktype_ should be a socket type such as: :STREAM, :DGRAM, :RAW, etc.
*
- * _protocol_ should be a protocol defined in the family.
- * 0 is default protocol for the family.
+ * _protocol_ should be a protocol defined in the family,
+ * and defaults to 0 for the family.
*
* _flags_ should be bitwise OR of Socket::AI_* constants.
*
@@ -1148,8 +1147,7 @@ sock_s_getservbyport(int argc, VALUE *argv)
* # ["AF_INET", 0, "localhost", "127.0.0.1", 2, 3, 0]] # PF_INET/SOCK_RAW/IPPROTO_IP
*
* _reverse_lookup_ directs the form of the third element, and has to
- * be one of below.
- * If it is ommitted, the default value is +nil+.
+ * be one of below. If _reverse_lookup_ is omitted, the default value is +nil+.
*
* +true+, +:hostname+: hostname is obtained from numeric address using reverse lookup, which may take a time.
* +false+, +:numeric+: hostname is same as numeric address.
@@ -1201,7 +1199,8 @@ sock_s_getaddrinfo(int argc, VALUE *argv)
*
* _flags_ should be bitwise OR of Socket::NI_* constants.
*
- * Note that the last form is compatible with IPSocket#{addr,peeraddr}.
+ * Note:
+ * The last form is compatible with IPSocket#addr and IPSocket#peeraddr.
*
* Socket.getnameinfo(Socket.sockaddr_in(80, "127.0.0.1")) #=> ["localhost", "www"]
* Socket.getnameinfo(["AF_INET", 80, "127.0.0.1"]) #=> ["localhost", "www"]
@@ -1859,35 +1858,45 @@ Init_socket()
* TCPSocket, UDPSocket or UNIXSocket for example.
*
* Sockets have their own vocabulary:
- * domain::
- * The family of protocols: Socket::PF_INET, Socket::PF_INET6,
- * Socket::PF_UNIX, etc.
- * type::
- * The type of communications between the two endpoints, typically
- * Socket::SOCK_STREAM or Socket::SOCK_DGRAM.
- * protocol::
- * Typically zero. This may be used to identify a variant of a
- * protocol.
- * hostname::
- * The identifier of a network interface:
- * * a string (hostname, IPv4 or IPv6 adress or <tt><broadcast></tt>
- * which specifies a broadcast address)
- * * a zero-length string which specifies INADDR_ANY
- * * an integer (interpreted as binary address in host byte order).
+ *
+ * *domain:*
+ * The family of protocols:
+ * * Socket::PF_INET
+ * * Socket::PF_INET6
+ * * Socket::PF_UNIX
+ * * etc.
+ *
+ * *type:*
+ * The type of communications between the two endpoints, typically
+ * * Socket::SOCK_STREAM
+ * * Socket::SOCK_DGRAM.
+ *
+ * *protocol:*
+ * Typically _zero_.
+ * This may be used to identify a variant of a protocol.
+ *
+ * *hostname:*
+ * The identifier of a network interface:
+ * * a string (hostname, IPv4 or IPv6 adress or +broadcast+
+ * which specifies a broadcast address)
+ * * a zero-length string which specifies INADDR_ANY
+ * * an integer (interpreted as binary address in host byte order).
*
* === Quick start
*
- * Some classes such as TCPSocket, UDPSocket or UNIXSocket ease use of
- * sockets of these types compared to C programming.
+ * Many of the classes, such as TCPSocket, UDPSocket or UNIXSocket,
+ * ease the use of sockets comparatively to the equivalent C programming interface.
+ *
+ * Let's create an internet socket using the IPv4 protocol in a C-like manner:
*
- * # Creating a TCP socket in a C-like manner
- * s = Socket.new Socket::INET, Socket::SOCK_STREAM
+ * s = Socket.new Socket::AF_INET, Socket::SOCK_STREAM
* s.connect Socket.pack_sockaddr_in(80, 'example.com')
*
- * # Using TCPSocket
+ * You could also use the TCPSocket class:
+ *
* s = TCPSocket.new 'example.com', 80
*
- * A simple server would look like:
+ * A simple server might look like this:
*
* require 'socket'
*
@@ -1900,7 +1909,7 @@ Init_socket()
* client.close
* end
*
- * A simple client may look like:
+ * A simple client may look like this:
*
* require 'socket'
*
@@ -1917,14 +1926,14 @@ Init_socket()
* Ruby's Socket implementation raises exceptions based on the error
* generated by the system dependent implementation. This is why the
* methods are documented in a way that isolate Unix-based system
- * exceptions from Windows based exceptions. If more information on
- * particular exception is needed please refer to the Unix manual pages or
+ * exceptions from Windows based exceptions. If more information on a
+ * particular exception is needed, please refer to the Unix manual pages or
* the Windows WinSock reference.
*
- * === Convenient methods
+ * === Convenience methods
*
* Although the general way to create socket is Socket.new,
- * there are several methods for socket creation for most cases.
+ * there are several methods of socket creation for most cases.
*
* TCP client socket::
* Socket.tcp, TCPSocket.open