| Summary: | KExtendedSocket listening constructor should be better documented | ||
|---|---|---|---|
| Product: | [Unmaintained] kdelibs | Reporter: | Linus McCabe <linus> |
| Component: | general | Assignee: | Thiago Macieira <thiago> |
| Status: | RESOLVED FIXED | ||
| Severity: | normal | ||
| Priority: | NOR | ||
| Version: | unspecified | ||
| Target Milestone: | --- | ||
| Platform: | unspecified | ||
| OS: | Linux | ||
| Latest Commit: | Version Fixed In: | ||
| Sentry Crash Report: | |||
|
Description
Linus McCabe
2004-05-11 20:48:15 UTC
docs package is for the user documentation... Please take a look at http://api.kde.org/cvs-api/libqt-addon/html/classQStreamSocket.html and tell me if the same problem affects the new API. The autogenerator doesn't generate documentation for the new server socket class, but you can get an idea from the QStreamSocket::bind method. It doesent seem like the new API has this documented neither, (assuming it works in a similar way to KExtendedSocket). Even so, can't the KExtendedSocket documentation be updated? It's only adding a line or two on a couple of places.. /linus I will. It's just that I've got some outstanding modifications to the source files, so I can't do it right now. Great, thanks! CVS commit by thiago: Deprecate the KExtendedSocket class. Use the KNetwork classes in the future. Also, fix the documentation by describing the procedure a bit more. CCMAIL:81362-done@bugs.kde.org M +48 -4 kextsock.h 1.46 --- kdelibs/kdecore/kextsock.h #1.45:1.46 @@ -29,4 +29,5 @@ #include "kbufferedio.h" #include "ksockaddr.h" +#include "kdemacros.h" /* External reference to netdb.h */ @@ -77,8 +78,13 @@ class KExtendedSocketPrivate; * support newer IP protocols, ipv4Socket | ipv6Socket is your guy. * + * @deprecated + * This class is now deprecated. Please use the classes in @ref KNetwork for + * new programs. In special, this class is replaced by @ref KNetwork::KStreamSocket + * and @ref KNetwork::KServerSocket. + * * @author Thiago Macieira <thiago.macieira@kdemail.net> * @short an extended socket */ -class KExtendedSocket: public KBufferedIO // public QObject, public QIODevice +class KDE_DEPRECATED KExtendedSocket: public KBufferedIO // public QObject, public QIODevice { Q_OBJECT @@ -153,4 +159,14 @@ public: /** * Creates a socket with the given hostname and port. + * + * If this is a connecting (active) socket, the hostname and port specify + * the remote address to which we will connect. + * + * If this is a listening (passive) socket, the hostname and port specify + * the address to listen on. In order to listen on every interface + * available on this node, set @p host to QString::null. To let the operating + * system select a port, set it to 0. + * + * @sa setAddress * @param host the hostname * @param port the port number @@ -161,4 +177,14 @@ public: /** * Creates a socket with the given hostname and service. + * + * If this is a connecting (active) socket, the hostname and service specify + * the remote address to which we will connect. + * + * If this is a listening (passive) socket, the hostname and service specify + * the address to listen on. In order to listen on every interface + * available on this node, set @p host to QString::null. To let the operating + * system select a port, set the service to "0". + * + * @sa setAddress * @param host the hostname * @param service the service @@ -215,4 +241,12 @@ public: /** * Sets the hostname to the given value. + * + * If this is a listening (passive) socket, the hostname is the host to which the socket + * will bind in order to listen. If you want to listen in every interface, set it + * to "*" or QString::null. + * + * If this is a connecting (active) socket, the hostname is the host to which we will try + * to connect. + * * @param host the hostname * @return true on success, false on error @@ -234,4 +268,8 @@ public: /** * Sets the port/service. + * + * In the case of Unix-domain sockets, the port is the filename for the socket. + * If the name is not an absolute path, "/tmp/" will be prepended. + * * @param port the port * @return true if successful, false on error (e.g. connection already established) @@ -247,4 +285,7 @@ public: /** * Sets the address where we will connect to. + * + * See @ref setHost and @ref setPort for information on the parameters. + * * @param host the hostname * @param port port number @@ -255,4 +296,7 @@ public: /** * Sets the address where we will connect to. + * + * See @ref setHost and @ref setPort for information on the parameters. + * * @param host the hostname * @param serv the service @@ -901,5 +945,5 @@ public: /** @deprecated - * This function is now deprecated. Please use @ref QResolver::resolve. + * This function is now deprecated. Please use @ref KNetwork::KResolver::resolve. * * Performs lookup on the given hostname/port combination and returns a list @@ -968,5 +1012,5 @@ private: /** @deprecated - * This class is now deprecated. Please see @ref QResolver for the new API. + * This class is now deprecated. Please see @ref KNetwork::KResolver for the new API. * * Contains information about an internet address. It wraps addrinfo, |