improve code documentation

2 files changed, 38 insertions, 14 deletions

diff --git a/source/QXmppTransferManager.cpp b/source/QXmppTransferManager.cpp
index 93b3634e..8b32f732 100644
--- a/source/QXmppTransferManager.cpp
+++ b/source/QXmppTransferManager.cpp
@@ -95,7 +95,7 @@ void QXmppTransferJob::checkData()
 
 /// Returns the job's data for a given role.
 ///
-/// You can associate arbitrary data with the role using setData.
+/// You can associate arbitrary data with the role using setData().
 
 QVariant QXmppTransferJob::data(int role) const
 {
@@ -112,11 +112,17 @@ void QXmppTransferJob::setData(int role, const QVariant &value)
     m_data.insert(role, value);
 }
 
+/// Returns the job's transfer direction.
+///
+
 QXmppTransferJob::Direction QXmppTransferJob::direction() const
 {
     return m_direction;
 }
 
+/// Returns the last error that was encoutered.
+///
+
 QXmppTransferJob::Error QXmppTransferJob::error() const
 {
     return m_error;
@@ -702,6 +708,10 @@ void QXmppTransferManager::jobStateChanged(QXmppTransferJob::State state)
     m_client->sendPacket(response);
 }
 
+/// Send file to a remote party.
+///
+/// The remote party will be given the choice to accept or refuse the transfer.
+///
 QXmppTransferJob *QXmppTransferManager::sendFile(const QString &jid, const QString &fileName)
 {
     QFileInfo info(fileName);
@@ -1130,6 +1140,8 @@ void QXmppTransferManager::setProxy(const QString &proxyJid)
 
 /// Return the supported stream methods.
 ///
+/// The methods are a combination of zero or more QXmppTransferJob::Method.
+///
 
 int QXmppTransferManager::supportedMethods() const
 {
diff --git a/source/QXmppTransferManager.h b/source/QXmppTransferManager.h
index 34d66b58..6e50830c 100644
--- a/source/QXmppTransferManager.h
+++ b/source/QXmppTransferManager.h
@@ -43,6 +43,11 @@ class QXmppSocksClient;
 class QXmppSocksServer;
 class QXmppStreamInitiationIq;
 
+/// The QXmppTransferJob class represent a single file transfer job.
+///
+/// \sa QXmppTransferManager
+///
+
 class QXmppTransferJob : public QObject
 {
     Q_OBJECT
@@ -50,25 +55,25 @@ class QXmppTransferJob : public QObject
 public:
     enum Direction
     {
-        IncomingDirection,
-        OutgoingDirection,
+        IncomingDirection, ///< The file is being received.
+        OutgoingDirection, ///< The file is being sent.
     };
 
     enum Error
     {
-        NoError = 0,
-        AbortError,
-        FileAccessError,
-        FileCorruptError,
-        ProtocolError,
+        NoError = 0,      ///< No error occured.
+        AbortError,       ///< The file transfer was aborted.
+        FileAccessError,  ///< An error was encountered trying to access a local file.
+        FileCorruptError, ///< The file is corrupt: the file size or hash do not match.
+        ProtocolError,    ///< An error was encountered in the file transfer protocol.
     };
 
     enum Method
     {
-        NoMethod = 0,
-        InBandMethod = 1,
-        SocksMethod = 2,
-        AnyMethod = 3,
+        NoMethod = 0,     ///< No transfer method.
+        InBandMethod = 1, ///< XEP-0047: In-Band Bytestreams
+        SocksMethod = 2,  ///< XEP-0065: SOCKS5 Bytestreams
+        AnyMethod = 3,    ///< Any supported transfer method.
     };
 
     enum State
@@ -160,6 +165,13 @@ private:
     friend class QXmppTransferManager;
 };
 
+/// The QXmppTransferManager class provides support for sending and receiving
+/// files.
+///
+/// Stream initiation is performed as described in XEP-0095: Stream Initiation
+/// and XEP-0096: SI File Transfer. The actual file transfer is then performed
+/// using either XEP-0065: SOCKS5 Bytestreams or XEP-0047: In-Band Bytestreams.
+/// 
 class QXmppTransferManager : public QObject
 {
     Q_OBJECT
@@ -175,8 +187,8 @@ public:
 signals:
     /// This signal is emitted when a new file transfer offer is received.
     ///
-    /// To accept the transfer job, call the job's accept() method.
-    /// To refuse the transfer job, call the job's abort() method.
+    /// To accept the transfer job, call the job's QXmppTransferJob::accept() method.
+    /// To refuse the transfer job, call the job's QXmppTransferJob::abort() method.
     void fileReceived(QXmppTransferJob *offer);
 
 private slots: