From 79d513dd7e0a1e5b8a9e7d821ef575b3e7f6f173 Mon Sep 17 00:00:00 2001
From: Dominik Riebeling <Dominik.Riebeling@gmail.com>
Date: Fri, 18 Dec 2015 23:10:29 +0100
Subject: Add documentation to HttpGet and remove unnecessary return value.

HttpGet::getFile() always returns the same value. Remove the return value since
it isn't necessary. Add some missing function documentation comments.

Change-Id: I1cee242211272a996437b10dbc8de791b3fc3d67
---
 rbutil/rbutilqt/base/httpget.cpp | 37 ++++++++++++++++++++++++++++++++-----
 rbutil/rbutilqt/base/httpget.h   |  2 +-
 2 files changed, 33 insertions(+), 6 deletions(-)

diff --git a/rbutil/rbutilqt/base/httpget.cpp b/rbutil/rbutilqt/base/httpget.cpp
index 4d10301bc0..476da87bad 100644
--- a/rbutil/rbutilqt/base/httpget.cpp
+++ b/rbutil/rbutilqt/base/httpget.cpp
@@ -44,8 +44,9 @@ HttpGet::HttpGet(QObject *parent)
 }
 
 
-//! @brief set cache path
-//  @param d new directory to use as cache path
+/** @brief set cache path
+ *  @param d new directory to use as cache path
+ */
 void HttpGet::setCache(const QDir& d)
 {
     if(m_cache && m_cachedir == d.absolutePath())
@@ -95,6 +96,9 @@ QByteArray HttpGet::readAll()
 }
 
 
+/** @brief Set and enable Proxy to use.
+ *  @param proxy Proxy URL.
+ */
 void HttpGet::setProxy(const QUrl &proxy)
 {
     LOG_INFO() << "Proxy set to" << proxy;
@@ -107,6 +111,9 @@ void HttpGet::setProxy(const QUrl &proxy)
 }
 
 
+/** @brief Enable or disable use of previously set proxy.
+ *  @param enable Enable proxy.
+ */
 void HttpGet::setProxy(bool enable)
 {
     if(enable) m_mgr->setProxy(m_proxy);
@@ -114,6 +121,14 @@ void HttpGet::setProxy(bool enable)
 }
 
 
+/** @brief Set output file.
+ *
+ *  Set filename for storing the downloaded file to. If no file is set the
+ *  downloaded file will not be stored to disk but kept in memory. The result
+ *  can then be retrieved using readAll().
+ *
+ *  @param file Output file.
+ */
 void HttpGet::setFile(QFile *file)
 {
     m_outputFile = file;
@@ -202,22 +217,34 @@ void HttpGet::networkError(QNetworkReply::NetworkError error)
 }
 
 
-bool HttpGet::getFile(const QUrl &url)
+/** @brief Retrieve the file pointed to by url.
+ *
+ *  Note: This also handles file:// URLs. Be aware that QUrl requires file://
+ *  URLs to be absolute, i.e. file://filename.txt doesn't work. Use
+ *  QDir::absoluteFilePath() to convert to an absolute path first.
+ *
+ *  @param url URL to download.
+ */
+void HttpGet::getFile(const QUrl &url)
 {
     LOG_INFO() << "Get URI" << url.toString();
     m_data.clear();
     startRequest(url);
-
-    return false;
 }
 
 
+/** @brief Retrieve string representation for most recent error.
+ *  @return Error string.
+ */
 QString HttpGet::errorString(void)
 {
     return m_lastErrorString;
 }
 
 
+/** @brief Return last HTTP response code.
+ *  @return Response code.
+ */
 int HttpGet::httpResponse(void)
 {
     return m_lastStatusCode;
diff --git a/rbutil/rbutilqt/base/httpget.h b/rbutil/rbutilqt/base/httpget.h
index 8c62157e5f..0bd3d284ac 100644
--- a/rbutil/rbutilqt/base/httpget.h
+++ b/rbutil/rbutilqt/base/httpget.h
@@ -34,7 +34,7 @@ class HttpGet : public QObject
     public:
         HttpGet(QObject *parent = 0);
 
-        bool getFile(const QUrl &url);
+        void getFile(const QUrl &url);
         void setProxy(const QUrl &url);
         void setProxy(bool);
         QString errorString(void);
-- 
cgit v1.2.3