Fix: use the deprecated annotation when possible (sockets)

Author: ysbaddaden

src/socket.cr

@@ -51,36 +51,40 @@ class Socket < IO
 
   # Creates a TCP socket. Consider using `TCPSocket` or `TCPServer` unless you
   # need full control over the socket.
-  #
-  # NOTE: The *blocking* arg is deprecated since Crystal 1.17. Use `#blocking=`
-  # to change the blocking mode after creating the socket.
-  def self.tcp(family : Family, blocking = nil) : self
+  def self.tcp(family : Family) : self
+    new(family, Type::STREAM, Protocol::TCP)
+  end
+
+  @[Deprecated("The blocking argument is deprecated. Use #blocking= to change it after creating the socket.")]
+  def self.tcp(family : Family, blocking) : self
     new(family, Type::STREAM, Protocol::TCP, blocking)
   end
 
   # Creates an UDP socket. Consider using `UDPSocket` unless you need full
   # control over the socket.
-  #
-  # NOTE: The *blocking* arg is deprecated since Crystal 1.17. Use `#blocking=`
-  # to change the blocking mode after creating the socket.
-  def self.udp(family : Family, blocking = nil) : self
+  def self.udp(family : Family) : self
+    new(family, Type::DGRAM, Protocol::UDP)
+  end
+
+  @[Deprecated("The blocking argument is deprecated. Use #blocking= to change it after creating the socket.")]
+  def self.udp(family : Family, blocking) : self
     new(family, Type::DGRAM, Protocol::UDP, blocking)
   end
 
   # Creates an UNIX socket. Consider using `UNIXSocket` or `UNIXServer` unless
   # you need full control over the socket.
   #
-  # NOTE: The *blocking* arg is deprecated since Crystal 1.17. Use `#blocking=`
-  # to change the blocking mode after creating the socket.
+  # NOTE: The *blocking* argument is deprecated. Use `#blocking=` to change it
+  # after creating the socket.
   def self.unix(type : Type = Type::STREAM, blocking = nil) : self
     new(Family::UNIX, type, blocking: blocking)
   end
 
   # Creates a socket. Consider using `TCPSocket`, `TCPServer`, `UDPSocket`,
   # `UNIXSocket` or `UNIXServer` unless you need full control over the socket.
   #
-  # NOTE: The *blocking* arg is deprecated since Crystal 1.17. Use `#blocking=`
-  # to change the blocking mode after creating the socket.
+  # NOTE: The *blocking* argument is deprecated since Crystal 1.17. Use
+  # `#blocking=` to change it after creating the socket.
   def initialize(family : Family, type : Type, protocol : Protocol = Protocol::IP, blocking = nil)
     # This method is `#initialize` instead of `.new` because it is used as super
     # constructor from subclasses.
@@ -95,8 +99,8 @@ class Socket < IO
   # event loop runtime requirements.
   #
   # NOTE: On Windows the handle must have been created with `WSA_FLAG_OVERLAPPED`.
-  # NOTE: The *blocking* arg is deprecated since Crystal 1.17. Use `#blocking=`
-  # to change the blocking mode after creating the socket.
+  # NOTE: The *blocking* argument is deprecated since Crystal 1.17. Use
+  # `#blocking=` to change it after creating the socket.
   def initialize(fd, @family : Family, @type : Type, @protocol : Protocol = Protocol::IP, blocking = nil)
     initialize(handle: fd, family: family, type: type, protocol: protocol)
     blocking = Crystal::EventLoop.default_socket_blocking? if blocking.nil?

src/socket/tcp_socket.cr

@@ -16,8 +16,8 @@ require "./ip_socket"
 class TCPSocket < IPSocket
   # Creates a new `TCPSocket`, waiting to be connected.
   #
-  # NOTE: The *blocking* arg is deprecated since Crystal 1.17. Use
-  # `Socket#blocking=` to change the blocking mode after creating the socket.
+  # NOTE: The *blocking* argument is deprecated since Crystal 1.17. Use
+  # `Socket#blocking=` to change it after creating the socket.
   def self.new(family : Family = Family::INET, blocking = nil)
     super(family, Type::STREAM, Protocol::TCP, blocking)
   end
@@ -28,8 +28,8 @@ class TCPSocket < IPSocket
   # connection time to the remote server with `connect_timeout`. Both values
   # must be in seconds (integers or floats).
   #
-  # NOTE: The *blocking* arg is deprecated since Crystal 1.17. Use
-  # `Socket#blocking=` to change the blocking mode after creating the socket.
+  # NOTE: The *blocking* argument is deprecated since Crystal 1.17. Use
+  # `Socket#blocking=` to change it after creating the socket.
   def initialize(host : String, port, dns_timeout = nil, connect_timeout = nil, blocking = nil)
     Addrinfo.tcp(host, port, timeout: dns_timeout) do |addrinfo|
       super(addrinfo.family, addrinfo.type, addrinfo.protocol, blocking)
@@ -44,7 +44,8 @@ class TCPSocket < IPSocket
     super family, type, protocol
   end
 
-  # constructor for TCPServer#accept?
+  # Internal constructor for TCPServer#accept?
+  # The *blocking* arg is purely informational.
   protected def initialize(*, handle, family, type, protocol, blocking)
     super(handle: handle, family: family, type: type, protocol: protocol, blocking: blocking)
   end
@@ -56,8 +57,8 @@ class TCPSocket < IPSocket
   # event loop runtime requirements.
   #
   # NOTE: On Windows the handle must have been created with `WSA_FLAG_OVERLAPPED`.
-  # NOTE: The *blocking* arg is deprecated since Crystal 1.17. Use
-  # `Socket#blocking=` to change the blocking mode after creating the socket.
+  # NOTE: The *blocking* argument is deprecated since Crystal 1.17. Use
+  # `Socket#blocking=` to change it after creating the socket.
   def initialize(*, fd : Handle, family : Family = Family::INET, blocking = nil)
     super fd, family, Type::STREAM, Protocol::TCP, blocking
   end

src/socket/unix_socket.cr

@@ -33,6 +33,7 @@ class UNIXSocket < Socket
   end
 
   # Internal constructor for UNIXSocket#pair and UNIXServer#accept?
+  # The *blocking* arg is purely informational.
   protected def initialize(*, handle : Handle, type : Type = Type::STREAM, path : Path | String? = nil, blocking : Bool = nil)
     @path = path.to_s
     super handle: handle, family: Family::UNIX, type: type, protocol: Protocol::IP, blocking: blocking