[m-rev.] diff: extras/net: Document sockets.m

[Paul Bone]

extras/net: Document sockets.m

sockets.m:
    As above.
---
 extras/net/sockets.m | 75 +++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 60 insertions(+), 15 deletions(-)

diff --git a/extras/net/sockets.m b/extras/net/sockets.m
index 012c198..e2f4b47 100644
--- a/extras/net/sockets.m
+++ b/extras/net/sockets.m
@@ -34,44 +34,71 @@
 
 %-----------------------------------------------------------------------------%
 
-:- pred sockets.gethostbyname(string::in, string::out,
-    io::di, io::uo) is det.
+    % gethostbyname(Hostname, RealName, !IO),
+    %
+    % Note, this does not return the address of the host, it returns the
+    % "official name of the host" gethostbyname(3), this may be a mistake.
+    %
+:- pred gethostbyname(string::in, string::out, io::di, io::uo) is det.
 
-:- pred sockets.getservbyname(string::in, string::in, int::out,
-    io::di, io::uo) is det.
+    % getservbyname(ServiceName, Protocol, PortNum, !IO),
+    %
+    % Lookup the port number for a service name (eg "http") and a protocol
+    % (eg "tcp").  If the service was not found then -1 is returned.
+    %
+:- pred getservbyname(string::in, string::in, int::out, io::di, io::uo) is det.
 
-:- pred sockets.socket(int::in, int::in, int::in, sockets.res(int)::out,
+    % socket(Domain, Type, Protocol, Result, !IO),
+    %
+    % Create a new socket.
+    %
+:- pred socket(int::in, int::in, int::in, sockets.res(int)::out,
     io::di, io::uo) is det.
 
-:- pred sockets.port_address(string::in, int::in, sockets.res(c_pointer)::out,
+    % port_address(Host, Port, Result, !IO),
+    %
+    % Lookup a hostname and build an address structure with the resulting
+    % address and the given port.
+    %
+:- pred port_address(string::in, int::in, sockets.res(c_pointer)::out,
     io::di, io::uo) is det.
 
-:- pred sockets.service_address(string::in, string::in,
+    % service_address(Host, Service, Result, !IO),
+    %
+:- pred service_address(string::in, string::in,
     sockets.res(c_pointer)::out, io::di, io::uo) is det.
 
     % connect(Fd, Addr, Addrlen, Result, !IO),
     %
     % XXX: Where does the caller get the Addrlen parameter from?
     %
-:- pred sockets.connect(int::in, c_pointer::in, int::in, sockets.res::out,
+:- pred connect(int::in, c_pointer::in, int::in, sockets.res::out,
     io::di, io::uo) is det.
 
-:- pred sockets.bind(int::in, c_pointer::in, int::in, sockets.res::out,
+    % bind(Fd, Addr, Addrlen, Result, !IO),
+    %
+:- pred bind(int::in, c_pointer::in, int::in, sockets.res::out,
     io::di, io::uo) is det.
 
-:- pred sockets.listen(int::in, int::in, sockets.res::out, io::di, io::uo)
+    % listen(Fd, Backlog, Result, !IO),
+    %
+:- pred listen(int::in, int::in, sockets.res::out, io::di, io::uo)
     is det.
 
+    % accept(Fd, Addr, Result, !IO),
+    %
     % Accept will block until a connection to our socket is made.
     %
-:- pred sockets.accept(int::in, c_pointer::in, sockets.res(int)::out,
+:- pred accept(int::in, c_pointer::in, sockets.res(int)::out,
     io::di, io::uo) is det.
 
+    % close(Fd, Result, !IO),
+    %
     % This closes the socket with lingering enabled.  The call will not
     % return until all the queued data has been sent or he timeout expires
     % (2 seconds).
     %
-:- pred sockets.close(int::in, sockets.res::out, io::di, io::uo) is det.
+:- pred close(int::in, sockets.res::out, io::di, io::uo) is det.
 
 %-----------------------------------------------------------------------------%
 %-----------------------------------------------------------------------------%
@@ -107,12 +134,12 @@
 
 %-----------------------------------------------------------------------------%
 
-:- initialise sockets.init/2.
+:- initialise init/2.
 
-:- pred sockets.init(io::di, io::uo) is det.
+:- pred init(io::di, io::uo) is det.
 
 :- pragma foreign_proc(c,
-    sockets.init(_IO0::di, _IO::uo),
+    init(_IO0::di, _IO::uo),
     [will_not_call_mercury, thread_safe, promise_pure, tabled_for_io],
 "
 #ifdef MR_WIN32
@@ -135,6 +162,8 @@
 #endif /* MR_WIN32 */
 ").
 
+%-----------------------------------------------------------------------------%
+
     % XXX not thread safe.
 :- pragma foreign_proc(c,
     gethostbyname(Name::in, Host::out, _IO0::di, _IO::uo),
@@ -159,6 +188,8 @@
     }
 ").
 
+%-----------------------------------------------------------------------------%
+
 socket(Domain, Type, Protocol, MaybeSocket, !IO) :-
     socket(Domain, Type, Protocol, Socket, Success, Errno, !IO),
     (
@@ -186,6 +217,8 @@ socket(Domain, Type, Protocol, MaybeSocket, !IO) :-
     }
 ").
 
+%-----------------------------------------------------------------------------%
+
 port_address(Host, Port, MaybeSA, !IO) :-
     port_address(Host, Port, SA, Success, Errno, !IO),
     (
@@ -225,6 +258,8 @@ port_address(Host, Port, MaybeSA, !IO) :-
     }
 ").
 
+%-----------------------------------------------------------------------------%
+
 service_address(Service, Host, MaybeSA, !IO) :-
     service_address(Service, Host, SA, Success, Errno, !IO),
     (
@@ -270,6 +305,8 @@ service_address(Service, Host, MaybeSA, !IO) :-
     }
 ").
 
+%-----------------------------------------------------------------------------%
+
 connect(Fd, Addr, AddrLen, Result, !IO) :-
     connect(Fd, Addr, AddrLen, Success, Errno, !IO),
     (
@@ -297,6 +334,8 @@ connect(Fd, Addr, AddrLen, Result, !IO) :-
     }
 ").
 
+%-----------------------------------------------------------------------------%
+
 bind(Fd, Addr, AddrLen, Result, !IO) :-
     bind(Fd, Addr, AddrLen, Success, Errno, !IO),
     (
@@ -324,6 +363,8 @@ bind(Fd, Addr, AddrLen, Result, !IO) :-
     }
 ").
 
+%-----------------------------------------------------------------------------%
+
 listen(Fd, Backlog, Result, !IO) :-
     listen(Fd, Backlog, Success, Errno, !IO),
     (
@@ -349,6 +390,8 @@ listen(Fd, Backlog, Result, !IO) :-
     }
 ").
 
+%-----------------------------------------------------------------------------%
+
 accept(Fd, Addr, MaybeNewSocket, !IO) :-
     accept(Fd, Addr, NewSocket, Success, Errno, !IO),
     (
@@ -377,6 +420,8 @@ accept(Fd, Addr, MaybeNewSocket, !IO) :-
     }
 ").
 
+%-----------------------------------------------------------------------------%
+
 close(Fd, Result, !IO) :-
     close(Fd, Success, Errno, !IO),
     (
-- 
2.1.0.rc1