[telepathy-qt4/master] FileTransferChannel: Improved docs according to review suggestions.

[Andre Moreira Magalhaes (andrunko)]

---
 TelepathyQt4/file-transfer-channel.cpp          |   18 ++++++++++++++----
 TelepathyQt4/incoming-file-transfer-channel.cpp |    2 ++
 TelepathyQt4/outgoing-file-transfer-channel.cpp |    2 ++
 3 files changed, 18 insertions(+), 4 deletions(-)

diff --git a/TelepathyQt4/file-transfer-channel.cpp b/TelepathyQt4/file-transfer-channel.cpp
index 5eec136..5c74c2f 100644
--- a/TelepathyQt4/file-transfer-channel.cpp
+++ b/TelepathyQt4/file-transfer-channel.cpp
@@ -229,7 +229,7 @@ FileTransferStateChangeReason FileTransferChannel::stateReason() const
 }
 
 /**
- * Return the name of the file on the sender's side. This is therefore given as
+ * Return the name of the file on the sender's side. This is given as
  * a suggested filename for the receiver. This cannot change once the channel
  * has been created.
  *
@@ -273,6 +273,12 @@ QString FileTransferChannel::contentType() const
  * The size of the file. This cannot change once the channel has been
  * created.
  *
+ * Note that the size is not guaranteed to be exactly right for
+ * incoming files. This is merely a hint and should not be used to know when the
+ * transfer finished.
+ *
+ * For unknown sizes the return value can be UINT64_MAX.
+ *
  * This method requires FileTransferChannel::FeatureCore to be enabled.
  *
  * \return The size of the file.
@@ -310,8 +316,8 @@ FileHashType FileTransferChannel::contentHashType() const
  * the value of the contentHashType().
  *
  * Its value MUST correspond to the appropriate type of the contentHashType().
- * If the contentHashType() is set to %FileHashTypeNone,
- * then this value should be ignored.
+ * If the contentHashType() is set to %FileHashTypeNone, then the
+ * returned value is an empty string.
  *
  * This method requires FileTransferChannel::FeatureCore to be enabled.
  *
@@ -325,6 +331,10 @@ QString FileTransferChannel::contentHash() const
             "calling contentHash";
     }
 
+    if (mPriv->contentHashType == FileHashTypeNone) {
+        return QString();
+    }
+
     return mPriv->contentHash;
 }
 
@@ -365,7 +375,7 @@ QDateTime FileTransferChannel::lastModificationTime() const
 }
 
 /**
- * Return the offset in bytes from where the file should be sent.
+ * Return the offset in bytes from which the file will be sent.
  *
  * This method requires FileTransferChannel::FeatureCore to be enabled.
  *
diff --git a/TelepathyQt4/incoming-file-transfer-channel.cpp b/TelepathyQt4/incoming-file-transfer-channel.cpp
index a1fc885..d44d6f0 100644
--- a/TelepathyQt4/incoming-file-transfer-channel.cpp
+++ b/TelepathyQt4/incoming-file-transfer-channel.cpp
@@ -115,6 +115,8 @@ IncomingFileTransferChannel::~IncomingFileTransferChannel()
  * The given output device should not be closed/destroyed until the state()
  * changes to %FileTransferStateCompleted or %FileTransferStateCancelled.
  *
+ * Only the primary handler of a file transfer channel may call this method.
+ *
  * This method requires FileTransferChannel::FeatureCore to be enabled.
  *
  * \param offset The desired offset in bytes where the file transfer should
diff --git a/TelepathyQt4/outgoing-file-transfer-channel.cpp b/TelepathyQt4/outgoing-file-transfer-channel.cpp
index 7cb0925..773a2e1 100644
--- a/TelepathyQt4/outgoing-file-transfer-channel.cpp
+++ b/TelepathyQt4/outgoing-file-transfer-channel.cpp
@@ -121,6 +121,8 @@ OutgoingFileTransferChannel::~OutgoingFileTransferChannel()
  * If input is a sequential device QIODevice::isSequential(), it should be
  * closed when no more data is available, so we know when to stop reading.
  *
+ * Only the primary handler of a file transfer channel may call this method.
+ *
  * This method requires FileTransferChannel::FeatureCore to be enabled.
  *
  * \param input A QIODevice object where the data will be read from.
-- 
1.5.6.5