Added examples to asyncftpclient module.

lib/pure/asyncftpclient.nim

@@ -6,23 +6,74 @@
 #    distribution, for details about the copyright.
 #
 
-## This module implement an asynchronous FTP client.
+## This module implements an asynchronous FTP client. It allows you to connect
+## to an FTP server and perform operations on it such as for example:
 ##
-## Examples
+## * The upload of new files.
-## --------
+## * The removal of existing files.
+## * Download of files.
+## * Changing of files' permissions.
+## * Navigation through the FTP server's directories.
 ##
-## .. code-block::nim
+## Connecting to an FTP server
+## ------------------------
 ##
-##      var ftp = newAsyncFtpClient("example.com", user = "test", pass = "test")
+## In order to begin any sort of transfer of files you must first
-##      proc main(ftp: AsyncFtpClient) {.async.} =
+## connect to an FTP server. You can do so with the ``connect`` procedure.
+##
+##   .. code-block::nim
+##      import asyncdispatch, asyncftpclient
+##      proc main() {.async.} =
+##        var ftp = newAsyncFtpClient("example.com", user = "test", pass = "test")
 ##        await ftp.connect()
-##        echo await ftp.pwd()
+##        echo("Connected")
-##        echo await ftp.listDirs()
+##      waitFor(main())
-##        await ftp.store("payload.jpg", "payload.jpg")
-##        await ftp.retrFile("payload.jpg", "payload2.jpg")
-##        echo("Finished")
 ##
-##      waitFor main(ftp)
+## A new ``main`` async procedure must be declared to allow the use of the
+## ``await`` keyword. The connection will complete asynchronously and the
+## client will be connected after the ``await ftp.connect()`` call.
+##
+## Uploading a new file
+## --------------------
+##
+## After a connection is made you can use the ``store`` procedure to upload
+## a new file to the FTP server. Make sure to check you are in the correct
+## working directory before you do so with the ``pwd`` procedure, you can also
+## instead specify an absolute path.
+##
+##   .. code-block::nim
+##      import asyncdispatch, asyncftpclient
+##      proc main() {.async.} =
+##        var ftp = newAsyncFtpClient("example.com", user = "test", pass = "test")
+##        await ftp.connect()
+##        let currentDir = await ftp.pwd()
+##        assert currentDir == "/home/user/"
+##        await ftp.store("file.txt", "file.txt")
+##        echo("File finished uploading")
+##      waitFor(main())
+##
+## Checking the progress of a file transfer
+## ----------------------------------------
+##
+## The progress of either a file upload or a file download can be checked
+## by specifying a ``onProgressChanged`` procedure to the ``store`` or
+## ``retrFile`` procedures.
+##
+##   .. code-block::nim
+##      import asyncdispatch, asyncftpclient
+##
+##      proc onProgressChanged(total, progress: BiggestInt,
+##                              speed: float): Future[void] =
+##        echo("Uploaded ", progress, " of ", total, " bytes")
+##        echo("Current speed: ", speed, " kb/s")
+##
+##      proc main() {.async.} =
+##        var ftp = newAsyncFtpClient("example.com", user = "test", pass = "test")
+##        await ftp.connect()
+##        await ftp.store("file.txt", "/home/user/file.txt", onProgressChanged)
+##        echo("File finished uploading")
+##      waitFor(main())
+
 
 import asyncdispatch, asyncnet, strutils, parseutils, os, times