Merge pull request #10981 from AndreaBruzz/patch-1

kernel: Document `inet:gethostbyname/3`, `inet:gethostbyaddr/2`, `inet:getaddr/3`, and `inet:getaddrs/3`.

Author: RaimoNiskanen

lib/kernel/src/inet.erl

@@ -2555,15 +2555,7 @@ gethostbyname(Name) ->
 	    gethostbyname_tm(Name, inet, false)
     end.
 
--doc """
-Resolve a hostname to a [`#hostent{}`](`t:hostent/0`) record,
-in a specific address family.
-
-Returns a [`#hostent{}`](`t:hostent/0`) record for the host
-with the specified `Hostname`, restricted to the specified address `Family`.
-
-See also `gethostbyname/1`.
-""".
+-doc(#{equiv => gethostbyname(Hostname, Family, infinity)}).
 -spec gethostbyname(Hostname, Family) ->
                            {ok, Hostent} | {error, posix()} when
       Hostname :: hostname(),
@@ -2573,7 +2565,17 @@ See also `gethostbyname/1`.
 gethostbyname(Name, Family) ->
     gethostbyname_tm(Name, Family, false).
 
--doc false.
+-doc """
+Resolve a hostname to a [`#hostent{}`](`t:hostent/0`) record,
+in a specific address family.
+
+Returns a [`#hostent{}`](`t:hostent/0`) record for the host
+with the specified `Name`, restricted to the specified address `Family`.
+
+`Timeout` specifies a time-out in milliseconds, or the atom `infinity`.
+
+See also `gethostbyname/1`.
+""".
 -spec gethostbyname(Name :: hostname(),
 	            Family :: address_family(),
 	            Timeout :: non_neg_integer() | 'infinity') ->
@@ -2603,20 +2605,22 @@ gethostbyname_tm(Name, Family, Timer) ->
     gethostbyname_tm(Name, Family, Timer, Opts).
 
 
--doc """
-Resolve (reverse) an address to a [`#hostent{}`](`t:hostent/0`) record.
-
-Returns a [`#hostent{}`](`t:hostent/0`) record for the host
-with the specified address.
-""".
+-doc(#{equiv => gethostbyaddr(Address, infinity)}).
 -spec gethostbyaddr(Address) -> {ok, Hostent} | {error, posix()} when
       Address :: string() | ip_address(),
       Hostent :: hostent().
 
 gethostbyaddr(Address) ->
     gethostbyaddr_tm(Address, false).
 
--doc false.
+-doc """
+Resolve (reverse) an address to a [`#hostent{}`](`t:hostent/0`) record.
+
+Returns a [`#hostent{}`](`t:hostent/0`) record for the host
+with the specified address.
+
+`Timeout` specifies a time-out in milliseconds, or the atom `infinity`.
+""".
 -spec gethostbyaddr(Address :: string() | ip_address(),
 	            Timeout :: non_neg_integer() | 'infinity') ->
 	{'ok', #hostent{}} | {'error', posix()}.
@@ -2805,13 +2809,7 @@ getfd(Socket) ->
 %% Lookup an ip address
 %%
 
--doc """
-Resolve a host to an address, in a specific addresss family.
-
-Returns the [IP address](`t:ip_address/0`) for `Host` as a tuple of integers.
-`Host` can be an [IP address](`t:ip_address/0`), a single `t:hostname/0`,
-or a fully qualified `t:hostname/0`.
-""".
+-doc(#{equiv => getaddr(Host, Family, infinity)}).
 -spec getaddr(Host, Family) -> {ok, Address} | {error, posix()} when
       Host :: ip_address() | hostname(),
       Family :: address_family(),
@@ -2820,11 +2818,19 @@ or a fully qualified `t:hostname/0`.
 getaddr(Address, Family) ->
     getaddr(Address, Family, infinity).
 
--doc false.
+-doc """
+Resolve a host to an address, in a specific address family.
+
+Returns the [IP address](`t:ip_address/0`) for `Host` as a tuple of integers.
+`Host` can be an [IP address](`t:ip_address/0`), a single `t:hostname/0`,
+or a fully qualified `t:hostname/0`.
+
+`Timeout` specifies a time-out in milliseconds, or the atom `infinity`.
+""".
 -spec getaddr(Host :: ip_address() | hostname(),
-	      Family :: address_family(),
-	      Timeout :: non_neg_integer() | 'infinity') ->
-	{'ok', ip_address()} | {'error', posix()}.
+          Family :: address_family(),
+          Timeout :: non_neg_integer() | 'infinity') ->
+    {'ok', ip_address()} | {'error', posix()}.
 
 getaddr(Address, Family, Timeout) ->
     %% ?DBG([{address, Address}, {family, Family}, {timeout, Timeout}]),
@@ -2846,13 +2852,7 @@ getaddr_tm(Address, Family, Timer) ->
 	    Error
     end.
 
--doc """
-Resolve a host to a list of addresses, in a specific address family.
-
-Returns a list of all IP addresses for `Host`.
-`Host` can be an [IP address](`t:ip_address/0`),
-a single `t:hostname/0`, or a fully qualified `t:hostname/0`.
-""".
+-doc(#{equiv => getaddrs(Host, Family, infinity)}).
 -spec getaddrs(Host, Family) ->
 	{ok, Addresses} | {error, posix()} when
       Host :: ip_address() | hostname(),
@@ -2862,8 +2862,16 @@ a single `t:hostname/0`, or a fully qualified `t:hostname/0`.
 getaddrs(Address, Family) ->
     getaddrs(Address, Family, infinity).
 
--doc false.
--spec getaddrs(Host :: ip_address() | string() | atom(),
+-doc """
+Resolve a host to a list of addresses, in a specific address family.
+
+Returns a list of all IP addresses for `Host`.
+`Host` can be an [IP address](`t:ip_address/0`),
+a single `t:hostname/0`, or a fully qualified `t:hostname/0`.
+
+`Timeout` specifies a time-out in milliseconds, or the atom `infinity`.
+""".
+-spec getaddrs(Host :: ip_address() | hostname(),
 	       Family :: address_family(),
 	       Timeout :: non_neg_integer() | 'infinity') ->
 	{'ok', [ip_address()]} | {'error', posix()}.