loolwsd: doxygen comments added to all classes

Change-Id: Ia485c2dcec20a6840d46836a61f75a8e7e8762ed
Reviewed-on: https://gerrit.libreoffice.org/28128
Reviewed-by: Ashod Nakashian <ashnakash@gmail.com>
Tested-by: Ashod Nakashian <ashnakash@gmail.com>

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:

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:

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:

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:

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:

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:

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:

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:

loolwsd/LOKitClient.cpp

@@ -79,7 +79,7 @@ extern "C"
     }
 }
 
-
+/// The application class implementing a client.
 class LOKitClient: public Application
 {
 public:

loolwsd/LOOLKit.cpp

@@ -226,6 +226,7 @@ namespace
 
 }
 
+/// Connection thread with a client (via WSD).
 class Connection: public Runnable
 {
 public:

loolwsd/LOOLSession.hpp

@@ -28,6 +28,7 @@
 #include "TileCache.hpp"
 #include "Log.hpp"
 
+/// Base class of a client session.
 class LOOLSession
 {
 public:

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:

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:

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:

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:

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;

loolwsd/Log.hpp

@@ -48,6 +48,8 @@ namespace Log
         }
     } end;
 
+    /// Helper class to support implementing streaming
+    /// operator for logging.
     class StreamLogger
     {
         public:

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:

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:

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;

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:

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: