PropagateUpload: add a few comments

src/libsync/propagateupload.cpp

@@ -351,6 +351,8 @@ void PropagateUploadFileQNAM::startNextChunk()
         // Don't do parallel upload of chunk if this might be the last chunk because the server cannot handle that
         // https://github.com/owncloud/core/issues/11106
         // We return now and when the _jobs will be finished we will proceed the last chunk
+        // NOTE: Some other part of the code such as slotUploadProgress assume also that the last chunk
+        // is sent last.
         return;
     }
     quint64 fileSize = _item._size;
@@ -637,16 +639,20 @@ void PropagateUploadFileQNAM::slotUploadProgress(qint64 sent, qint64 total)
     if (progressChunk >= _chunkCount)
         progressChunk = _currentChunk - 1;
 
+    // amount is the number of bytes already sent by all the other chunks that were sent
+    // not including this one.
+    // FIXME: this assume all chunks have the same size, which is true only if the last chunk
+    // has not been finished (which should not happen because the last chunk is sent sequentially)
     quint64 amount = progressChunk * chunkSize();
+
     sender()->setProperty("byteWritten", sent);
-    // FIXME: This calculation will mess up if we at some point also send the last chunks in parallel.
-    // At the moment we send the last chunk sequentially.
     if (_jobs.count() > 1) {
         amount -= (_jobs.count() -1) * chunkSize();
         foreach (QObject *j, _jobs) {
             amount += j->property("byteWritten").toULongLong();
         }
     } else {
+        // sender() is the only current job, no need to look at the byteWritten properties
         amount += sent;
     }
     emit progress(_item, amount);

src/libsync/propagateupload.h

@@ -96,6 +96,12 @@ signals:
     void uploadProgress(qint64,qint64);
 };
 
+/**
+ * This job implements the assynchronous PUT
+ * If the server replies to a PUT with a OC-Finish-Poll url, we will query this url until the server
+ * replies with an etag
+ * https://github.com/owncloud/core/issues/12097
+ */
 class PollJob : public AbstractNetworkJob {
     Q_OBJECT
     SyncJournalDb *_journal;
@@ -123,12 +129,23 @@ signals:
 
 class PropagateUploadFileQNAM : public PropagateItemJob {
     Q_OBJECT
+
+    /**
+     * That's the start chunk that was stored in the database for resuming.
+     * In the non-resuming case it is 0.
+     * If we are resuming, this is the first chunk we need to send
+     */
     int _startChunk;
+    /**
+     * This is the next chunk that we need to send. Starting from 0 even if _startChunk != 0
+     * (In other words,  _startChunk + _currentChunk is really the number of the chunk we need to send next)
+     * (In other words, _currentChunk is the number of chunk that we already sent or start sending)
+     */
     int _currentChunk;
-    int _chunkCount;
+    int _chunkCount; /// Total number of chunks for this file
-    int _transferId;
+    int _transferId; /// transfer id (part of the url)
     QElapsedTimer _duration;
-    QVector<PUTFileJob*> _jobs;
+    QVector<PUTFileJob*> _jobs; /// network jobs that are currently in transit
     bool _finished; // Tells that all the jobs have been finished
 public:
     PropagateUploadFileQNAM(OwncloudPropagator* propagator,const SyncFileItem& item)