Update API doc

src/includes/aria2/aria2.h

@@ -113,18 +113,18 @@ A2Gid hexToGid(const std::string& hex);
 // Returns true if the |gid| is invalid.
 bool isNull(const A2Gid& gid);
 
-// This method adds new HTTP(S)/FTP/BitTorrent Magnet URI.  On
-// successful return, the |gid| includes the GID of newly added
-// download.  The |uris| includes URI to be downloaded.  For
-// BitTorrent Magnet URI, the |uris| must have only one element and it
-// should be BitTorrent Magnet URI. URIs in uris must point to the
-// same file. If you mix other URIs which point to another file, aria2
-// does not complain but download may fail. The |options| is a pair of
-// option name and value. If the |position| is not negative integer,
-// the new download is inserted at position in the waiting queue. If
-// the |position| is negative or the |position| is larger than the
-// size of the queue, it is appended at the end of the queue.  This
-// function returns 0 if it succeeds, or -1.
+// Adds new HTTP(S)/FTP/BitTorrent Magnet URI.  On successful return,
+// the |gid| includes the GID of newly added download.  The |uris|
+// includes URI to be downloaded.  For BitTorrent Magnet URI, the
+// |uris| must have only one element and it should be BitTorrent
+// Magnet URI. URIs in uris must point to the same file. If you mix
+// other URIs which point to another file, aria2 does not complain but
+// download may fail. The |options| is a pair of option name and
+// value. If the |position| is not negative integer, the new download
+// is inserted at position in the waiting queue. If the |position| is
+// negative or the |position| is larger than the size of the queue, it
+// is appended at the end of the queue.  This function returns 0 if it
+// succeeds, or -1.
 int addUri(Session* session,
            A2Gid& gid,
            const std::vector<std::string>& uris,
@@ -134,10 +134,27 @@ int addUri(Session* session,
 // Returns the array of active download GID.
 std::vector<A2Gid> getActiveDownload(Session* session);
 
+// Removes the download denoted by the |gid|. If the specified
+// download is in progress, it is stopped at first. The status of
+// removed download becomes DOWNLOAD_REMOVED. If the |force| is true,
+// removal will take place without any action which takes time such as
+// contacting BitTorrent tracker. This function returns 0 if it
+// succeeds, or -1.
 int removeDownload(Session* session, const A2Gid& gid, bool force = false);
 
+// Pauses the download denoted by the |gid|. The status of paused
+// download becomes DOWNLOAD_PAUSED. If the download is active, the
+// download is placed on the first position of waiting queue. As long
+// as the status is DOWNLOAD_PAUSED, the download will not start. To
+// change status to DOWNLOAD_WAITING, use unpauseDownload() function.
+// If the |force| is true, removal will take place without any action
+// which takes time such as contacting BitTorrent tracker. This
+// function returns 0 if it succeeds, or -1.
 int pauseDownload(Session* session, const A2Gid& gid, bool force = false);
 
+// Changes the status of the download denoted by the |gid| from
+// DOWNLOAD_PAUSED to DOWNLOAD_WAITING. This makes the download
+// eligible to restart. This function returns 0 if it succeeds, or -1.
 int unpauseDownload(Session* session, const A2Gid& gid);
 
 enum UriStatus {
@@ -179,8 +196,23 @@ struct DownloadHandle {
   virtual int getUploadSpeed() = 0;
   virtual size_t getNumPieces() = 0;
   virtual int getConnections() = 0;
+  // Returns the last error code occurred in this download. The error
+  // codes are defined in EXIT STATUS section of aria2c(1) man
+  // page. This value is only available for stopped/completed
+  // downloads.
   virtual int getErrorCode() = 0;
+  // Returns array of GIDs which are generated by the consequence of
+  // this download. For example, when aria2 downloaded Metalink file,
+  // it generates downloads described in it (see --follow-metalink
+  // option). This value is useful to track these auto generated
+  // downloads. If there is no such downloads, this function returns
+  // empty array.
   virtual const std::vector<A2Gid>& getFollowedBy() = 0;
+  // Returns the GID of a parent download. Some downloads are a part
+  // of another download. For example, if a file in Metalink has
+  // BitTorrent resource, the download of ".torrent" is a part of that
+  // file. If this download has no parent, the invalid GID is returned
+  // (isNull(gid) is true).
   virtual A2Gid getBelongsTo() = 0;
   virtual const std::string& getDir() = 0;
   virtual std::vector<FileData> getFiles() = 0;