Mon Aug 15 03:12:49 UTC 2016

loolwsd/Admin.hpp           |    3 +++
 loolwsd/AdminModel.hpp      |    4 ++++
 loolwsd/Auth.hpp            |    2 ++
 loolwsd/ChildSession.hpp    |    2 ++
 loolwsd/ClientSession.hpp   |    1 +
 loolwsd/Connect.cpp         |    5 +++--
 loolwsd/FileServer.hpp      |    3 ++-
 loolwsd/IoUtil.hpp          |    1 +
 loolwsd/LOKitClient.cpp     |    2 +-
 loolwsd/LOOLKit.cpp         |    1 +
 loolwsd/LOOLSession.hpp     |    1 +
 loolwsd/LOOLStress.cpp      |    3 ++-
 loolwsd/LOOLTool.cpp        |    3 ++-
 loolwsd/LOOLWSD.cpp         |    8 +++++++-
 loolwsd/LOOLWSD.hpp         |    2 ++
 loolwsd/Log.cpp             |    2 +-
 loolwsd/Log.hpp             |    2 ++
 loolwsd/PrisonerSession.hpp |    2 ++
 loolwsd/Storage.hpp         |    4 ++++
 loolwsd/TileCache.cpp       |    3 +++
 loolwsd/TileDesc.hpp        |    3 +++
 loolwsd/TraceFile.hpp       |    4 ++++
 22 files changed, 53 insertions(+), 8 deletions(-)

New commits:
commit 08909b2a3d770639fcee73d75d754438999de534
Author: Ashod Nakashian <ashod.nakashian at collabora.co.uk>
Date:   Sun Aug 14 00:01:13 2016 -0400

    loolwsd: doxygen comments added to all classes
    
    Change-Id: Ia485c2dcec20a6840d46836a61f75a8e7e8762ed
    Reviewed-on: https://gerrit.libreoffice.org/28128
    Reviewed-by: Ashod Nakashian <ashnakash at gmail.com>
    Tested-by: Ashod Nakashian <ashnakash at gmail.com>

diff --git a/loolwsd/Admin.hpp b/loolwsd/Admin.hpp
index 118d562..699b2e2 100644
--- a/loolwsd/Admin.hpp
+++ b/loolwsd/Admin.hpp
@@ -26,6 +26,7 @@
 
 class Admin;
 
+/// Admin requests over HTTP(S) handler.
 class AdminRequestHandler: public Poco::Net::HTTPRequestHandler
 {
 public:
@@ -111,6 +112,7 @@ private:
     unsigned _cpuStatsTaskInterval = 5000;
 };
 
+/// Memory statistics.
 class MemoryStats : public Poco::Util::TimerTask
 {
 public:
@@ -133,6 +135,7 @@ private:
     long _lastTotalMemory;
 };
 
+/// CPU statistics.
 class CpuStats : public Poco::Util::TimerTask
 {
 public:
diff --git a/loolwsd/AdminModel.hpp b/loolwsd/AdminModel.hpp
index 3a192b6..1fff82c 100644
--- a/loolwsd/AdminModel.hpp
+++ b/loolwsd/AdminModel.hpp
@@ -20,6 +20,7 @@
 #include "Log.hpp"
 #include "Util.hpp"
 
+/// A client view in Admin controller.
 class View
 {
 public:
@@ -38,6 +39,7 @@ private:
     std::time_t _end = 0;
 };
 
+/// A document in Admin controller.
 class Document
 {
 public:
@@ -85,6 +87,7 @@ private:
     std::time_t _end = 0;
 };
 
+/// An Admin session subscriber.
 class Subscriber
 {
 public:
@@ -123,6 +126,7 @@ private:
     std::time_t _end = 0;
 };
 
+/// The Admin controller implementation.
 class AdminModel
 {
 public:
diff --git a/loolwsd/Auth.hpp b/loolwsd/Auth.hpp
index 889de73..664cfc1 100644
--- a/loolwsd/Auth.hpp
+++ b/loolwsd/Auth.hpp
@@ -28,6 +28,7 @@ public:
     virtual bool verify(const std::string& token) = 0;
 };
 
+/// JWT Authorization.
 class JWTAuth: public AuthBase
 {
 public:
@@ -61,6 +62,7 @@ private:
     Poco::Crypto::RSADigestEngine _digestEngine;
 };
 
+/// OAuth Authorization.
 class OAuth : public AuthBase
 {
 public:
diff --git a/loolwsd/ChildSession.hpp b/loolwsd/ChildSession.hpp
index 5995397..ce58a4e 100644
--- a/loolwsd/ChildSession.hpp
+++ b/loolwsd/ChildSession.hpp
@@ -23,6 +23,8 @@ class CallbackWorker;
 typedef std::function<std::shared_ptr<lok::Document>(const std::string&, const std::string&, const std::string&, const std::string&, bool)> OnLoadCallback;
 typedef std::function<void(const std::string&)> OnUnloadCallback;
 
+/// Represents a client session, with the socket end-point,
+/// and handles all incoming UI traffic.
 class ChildSession final : public LOOLSession
 {
 public:
diff --git a/loolwsd/ClientSession.hpp b/loolwsd/ClientSession.hpp
index f02fcd5..b6126a5 100644
--- a/loolwsd/ClientSession.hpp
+++ b/loolwsd/ClientSession.hpp
@@ -16,6 +16,7 @@
 class DocumentBroker;
 class PrisonerSession;
 
+/// Represents client sessions and socket end-point in WSD.
 class ClientSession final : public LOOLSession, public std::enable_shared_from_this<ClientSession>
 {
 public:
diff --git a/loolwsd/Connect.cpp b/loolwsd/Connect.cpp
index eef9a66..f6cc287 100644
--- a/loolwsd/Connect.cpp
+++ b/loolwsd/Connect.cpp
@@ -71,7 +71,8 @@ using Poco::Util::Application;
 static bool closeExpected = false;
 static std::mutex coutMutex;
 
-class Output: public Runnable
+/// Prints incoming data from a WebSocket.
+class Output : public Runnable
 {
 public:
     Output(WebSocket& ws) :
@@ -132,7 +133,7 @@ public:
     WebSocket& _ws;
 };
 
-/** Program for interactive or scripted testing of a lool server. */
+/// Program for interactive or scripted testing of a lool server.
 class Connect: public Poco::Util::Application
 {
 public:
diff --git a/loolwsd/FileServer.hpp b/loolwsd/FileServer.hpp
index e2afc47..04bf7f1 100644
--- a/loolwsd/FileServer.hpp
+++ b/loolwsd/FileServer.hpp
@@ -24,6 +24,7 @@
 
 #include "Log.hpp"
 
+/// Handles file requests over HTTP(S).
 class FileServerRequestHandler: public Poco::Net::HTTPRequestHandler
 {
     std::string getRequestPathname(const Poco::Net::HTTPServerRequest& request);
@@ -37,7 +38,7 @@ public:
     void handleRequest(Poco::Net::HTTPServerRequest& request, Poco::Net::HTTPServerResponse& response) override;
 };
 
-// Singleton
+/// Singleton class to serve files over HTTP(S).
 class FileServer
 {
 public:
diff --git a/loolwsd/IoUtil.hpp b/loolwsd/IoUtil.hpp
index 3c6eeb9..a213497 100644
--- a/loolwsd/IoUtil.hpp
+++ b/loolwsd/IoUtil.hpp
@@ -45,6 +45,7 @@ namespace IoUtil
 
     ssize_t readFIFO(int pipe, char* buffer, ssize_t size);
 
+    /// Helper class to handle reading from a pipe.
     class PipeReader
     {
     public:
diff --git a/loolwsd/LOKitClient.cpp b/loolwsd/LOKitClient.cpp
index df36a49..330d521 100644
--- a/loolwsd/LOKitClient.cpp
+++ b/loolwsd/LOKitClient.cpp
@@ -79,7 +79,7 @@ extern "C"
     }
 }
 
-
+/// The application class implementing a client.
 class LOKitClient: public Application
 {
 public:
diff --git a/loolwsd/LOOLKit.cpp b/loolwsd/LOOLKit.cpp
index 5a37d42..4c9d545 100644
--- a/loolwsd/LOOLKit.cpp
+++ b/loolwsd/LOOLKit.cpp
@@ -226,6 +226,7 @@ namespace
 
 }
 
+/// Connection thread with a client (via WSD).
 class Connection: public Runnable
 {
 public:
diff --git a/loolwsd/LOOLSession.hpp b/loolwsd/LOOLSession.hpp
index 976e6dd..96bbefb 100644
--- a/loolwsd/LOOLSession.hpp
+++ b/loolwsd/LOOLSession.hpp
@@ -28,6 +28,7 @@
 #include "TileCache.hpp"
 #include "Log.hpp"
 
+/// Base class of a client session.
 class LOOLSession
 {
 public:
diff --git a/loolwsd/LOOLStress.cpp b/loolwsd/LOOLStress.cpp
index 9b7981c..5d5e374 100644
--- a/loolwsd/LOOLStress.cpp
+++ b/loolwsd/LOOLStress.cpp
@@ -46,7 +46,6 @@
 #include "test/helpers.hpp"
 
 /// Stress testing and performance/scalability benchmarking tool.
-
 class Stress: public Poco::Util::Application
 {
 public:
@@ -77,6 +76,7 @@ using Poco::Util::HelpFormatter;
 using Poco::Util::Option;
 using Poco::Util::OptionSet;
 
+/// Connection class with WSD.
 class Connection
 {
 public:
@@ -113,6 +113,7 @@ private:
     std::shared_ptr<Poco::Net::WebSocket> _ws;
 };
 
+/// Main thread class to replay a trace file.
 class Worker: public Runnable
 {
 public:
diff --git a/loolwsd/LOOLTool.cpp b/loolwsd/LOOLTool.cpp
index a79c8b5..b658108 100644
--- a/loolwsd/LOOLTool.cpp
+++ b/loolwsd/LOOLTool.cpp
@@ -46,7 +46,7 @@
 #include <Poco/Util/Application.h>
 #include <Poco/Util/OptionSet.h>
 
-/** Simple command-line tool for file format conversion. */
+/// Simple command-line tool for file format conversion.
 class Tool: public Poco::Util::Application
 {
 public:
@@ -78,6 +78,7 @@ using Poco::Util::HelpFormatter;
 using Poco::Util::Option;
 using Poco::Util::OptionSet;
 
+/// Thread class which performs the conversion.
 class Worker: public Runnable
 {
 public:
diff --git a/loolwsd/LOOLWSD.cpp b/loolwsd/LOOLWSD.cpp
index 58d5853..50ba851 100644
--- a/loolwsd/LOOLWSD.cpp
+++ b/loolwsd/LOOLWSD.cpp
@@ -1152,11 +1152,14 @@ public:
     }
 };
 
+/// External (client) connection handler factory.
+/// Creates handler objects.
 class ClientRequestHandlerFactory: public HTTPRequestHandlerFactory
 {
 public:
     ClientRequestHandlerFactory()
-        { }
+    {
+    }
 
     HTTPRequestHandler* createRequestHandler(const HTTPServerRequest& request) override
     {
@@ -1201,6 +1204,8 @@ public:
     }
 };
 
+/// Internal (prisoner) connection handler factory.
+/// Creates handler objects.
 class PrisonerRequestHandlerFactory: public HTTPRequestHandlerFactory
 {
 public:
@@ -1271,6 +1276,7 @@ std::atomic<unsigned> LOOLWSD::NumDocBrokers;
 std::atomic<unsigned> LOOLWSD::NumConnections;
 std::unique_ptr<TraceFileWriter> LOOLWSD::TraceDumper;
 
+/// Helper class to hold default configuration entries.
 class AppConfigMap : public Poco::Util::MapConfiguration
 {
 public:
diff --git a/loolwsd/LOOLWSD.hpp b/loolwsd/LOOLWSD.hpp
index 1544fd1..2f58ef3 100644
--- a/loolwsd/LOOLWSD.hpp
+++ b/loolwsd/LOOLWSD.hpp
@@ -26,6 +26,8 @@
 #include "TraceFile.hpp"
 #include "Util.hpp"
 
+/// The Server class which is responsible for all
+/// external interactions.
 class LOOLWSD: public Poco::Util::ServerApplication
 {
 public:
diff --git a/loolwsd/Log.cpp b/loolwsd/Log.cpp
index 11db618..7365c99 100644
--- a/loolwsd/Log.cpp
+++ b/loolwsd/Log.cpp
@@ -33,7 +33,7 @@ namespace Log
     using namespace Poco;
 
     static const Poco::Int64 epochStart = Poco::Timestamp().epochMicroseconds();
-    // help avoid destruction ordering issues.
+    /// Helper to avoid destruction ordering issues.
     struct StaticNames {
         std::atomic<bool> inited;
         std::string name;
diff --git a/loolwsd/Log.hpp b/loolwsd/Log.hpp
index f129b63..76c5605 100644
--- a/loolwsd/Log.hpp
+++ b/loolwsd/Log.hpp
@@ -48,6 +48,8 @@ namespace Log
         }
     } end;
 
+    /// Helper class to support implementing streaming
+    /// operator for logging.
     class StreamLogger
     {
         public:
diff --git a/loolwsd/PrisonerSession.hpp b/loolwsd/PrisonerSession.hpp
index 4be892e..3ee088c 100644
--- a/loolwsd/PrisonerSession.hpp
+++ b/loolwsd/PrisonerSession.hpp
@@ -15,6 +15,8 @@
 class DocumentBroker;
 class ClientSession;
 
+/// An internal end-point in WSD with Kit process
+/// for a given client.
 class PrisonerSession final : public LOOLSession, public std::enable_shared_from_this<PrisonerSession>
 {
 public:
diff --git a/loolwsd/Storage.hpp b/loolwsd/Storage.hpp
index 493676f..d4db4e4 100644
--- a/loolwsd/Storage.hpp
+++ b/loolwsd/Storage.hpp
@@ -26,6 +26,8 @@ class StorageBase
 {
 public:
 
+    /// Represents a file's attributes.
+    /// Used for local and network files.
     class FileInfo
     {
     public:
@@ -117,6 +119,7 @@ private:
     bool _isCopy;
 };
 
+/// WOPI protocol backed storage.
 class WopiStorage : public StorageBase
 {
 public:
@@ -137,6 +140,7 @@ public:
     bool saveLocalFileToStorage() override;
 };
 
+/// WebDAV protocol backed storage.
 class WebDAVStorage : public StorageBase
 {
 public:
diff --git a/loolwsd/TileCache.cpp b/loolwsd/TileCache.cpp
index 6622fea..5dd987e 100644
--- a/loolwsd/TileCache.cpp
+++ b/loolwsd/TileCache.cpp
@@ -72,6 +72,9 @@ TileCache::~TileCache()
     Log::info("~TileCache dtor for uri [" + _docURL + "].");
 }
 
+/// Tracks the rendering of a given tile
+/// to avoid duplication and help clock
+/// rendering latency.
 struct TileCache::TileBeingRendered
 {
     std::vector<std::weak_ptr<ClientSession>> _subscribers;
diff --git a/loolwsd/TileDesc.hpp b/loolwsd/TileDesc.hpp
index 8759678..9d5f82c 100644
--- a/loolwsd/TileDesc.hpp
+++ b/loolwsd/TileDesc.hpp
@@ -137,6 +137,9 @@ private:
     int _id;
 };
 
+/// One or more tile header.
+/// Used to request the rendering of multiple
+/// tiles as well as the header of the response.
 class TileCombined
 {
 private:
diff --git a/loolwsd/TraceFile.hpp b/loolwsd/TraceFile.hpp
index eee746f..8b25252 100644
--- a/loolwsd/TraceFile.hpp
+++ b/loolwsd/TraceFile.hpp
@@ -41,6 +41,8 @@ public:
     std::string Payload;
 };
 
+/// Trace-file generator class.
+/// Writes records into a trace file.
 class TraceFileWriter
 {
 public:
@@ -127,6 +129,8 @@ private:
     std::mutex _mutex;
 };
 
+/// Trace-file parser class.
+/// Reads records from a trace file.
 class TraceFileReader
 {
 public:
