Add docs for entities

sea_transport/entities/IEntity.h

@@ -4,10 +4,20 @@
 #include "ISerializable.h"
 
 
+//! Alias type for any entity ID
 typedef unsigned long long entity_id;
 
+/**
+ * @brief Base interface for all entities
+ * 
+ */
 class IEntity : public ISerializable {
 public:
+   /**
+    * @brief Getter function for entity identificator
+    * 
+    * @return entity_id entity identficator
+    */
    virtual entity_id id() const = 0;
 };
 

sea_transport/entities/ISerializable.h

@@ -3,10 +3,23 @@
 
 #include <QDataStream>
 
-
+/**
+ * @brief Interface for any serializable object
+ * 
+ */
 class ISerializable {
 public:
+    /**
+     * @brief Write-obect-to-disk function
+     * 
+     * @param output output stream
+     */
     virtual void serialize(QDataStream &output) = 0;
+    /**
+     * @brief Read-object-from-disk function
+     * 
+     * @param input input stream
+     */
     virtual void deserialize(QDataStream &input) = 0;
 };
 

sea_transport/entities/cargo_entity.h

@@ -8,25 +8,68 @@
 #include <QCryptographicHash>
 
 
+/**
+ * @brief Cargo entity class
+ * 
+ */
 class cargo_entity : public IEntity {
 private:
+    //! Global static ID for cargo
     static entity_id __global_id;
 
+    //! Cargo's ID
     entity_id _id = 0;
+    //! Cargo title
     QString _title;
+    //! Cargo volume
     unsigned int _volume = 50000;
 
 public:
+    /**
+    * @brief Construct a new cargo entity object
+    * 
+    */
     cargo_entity();
+    /**
+     * @brief Construct a new cargo entity object
+     * 
+     * @param title cargo title
+     * @param volume cargo volume
+     */
     cargo_entity(const QString &title, unsigned int volume);
 
+    /**
+     * @brief Get cargo's ID
+     * 
+     * @return entity_id 
+     */
     entity_id id() const;
+    /**
+     * @brief Get cargo's title
+     * 
+     * @return QString 
+     */
     QString title() const;
+    /**
+     * @brief Get cargo's volume
+     * 
+     * @return unsigned int 
+     */
     unsigned int volume() const;
 
     void serialize(QDataStream &output);
     void deserialize(QDataStream &input);
+    /**
+     * @brief Sets GID of class
+     * 
+     * @param gid new class GID
+     */
     static void preloadGlobalId(entity_id gid);
+    /**
+     * @brief Returns GID of class
+     * 
+     * @return entity_id 
+     */
     static entity_id GID();
 };
 

sea_transport/entities/dpoint_entity.h

@@ -12,30 +12,102 @@
 
 class dpoint_entity : public IEntity {
 private:
+    //! Global static ID for delivery point
     static entity_id __global_id;
 
+    //! Delivery point ID
     entity_id _id = 0;
+    //! Delivery point dispatcher
     entity_id _dispatcher_id;
+    //! Delivery point title
     QString _title;
+    //! Delivery point storage collection
     QVector<storage_entity> _storages;
 
 public:
+    /**
+     * @brief Construct a new dpoint entity object
+     * 
+     */
     dpoint_entity();
+    /**
+     * @brief Construct a new dpoint entity object
+     * 
+     * @param dispatcher_id dispatcher's ID
+     * @param title DP's title
+     */
     dpoint_entity(entity_id dispatcher_id, const QString &title);
 
+    /**
+     * @brief Get delivery point ID
+     * 
+     * @return entity_id 
+     */
     entity_id id() const;
+    /**
+     * @brief Get delivery point dispatcher
+     * 
+     * @return entity_id 
+     */
     entity_id dispatcher() const;
+    /**
+     * @brief Get delivery point title
+     * 
+     * @return QString 
+     */
     QString title() const;
+    /**
+     * @brief Set delivery point title
+     * 
+     * @param new_title new title
+     */
     void set_title(const QString &new_title);
+    /**
+     * @brief Get immutable delivery point's storages collection
+     * 
+     * @return const QVector<storage_entity> 
+     */
     const QVector<storage_entity> storages();
+    /**
+     * @brief Get delivery point's storage
+     * 
+     * @param sid storage ID
+     * @param success object found reference
+     * @return storage_entity* 
+     */
     storage_entity* get_storage(entity_id sid, bool &success);
+    /**
+     * @brief Set storages of delivery point
+     * 
+     * @param storages new storages collection
+     */
     void set_storages(QVector<storage_entity> storages);
+    /**
+     * @brief Remove storage from delivery point's collection
+     * 
+     * @param sid storage ID
+     */
     void remove_storage(entity_id sid);
+    /**
+     * @brief Add storage entity to delivery point's collection
+     * 
+     * @param ent new storage
+     */
     void add_storage(storage_entity ent);
 
     void serialize(QDataStream &output);
     void deserialize(QDataStream &input);
+    /**
+     * @brief Sets GID of class
+     * 
+     * @param gid new class GID
+     */
     static void preloadGlobalId(entity_id gid);
+    /**
+     * @brief Returns GID of class
+     * 
+     * @return entity_id 
+     */
     static entity_id GID();
 };
 

sea_transport/entities/storage_entity.h

@@ -8,30 +8,96 @@
 #include <QRandomGenerator>
 
 
+/**
+ * @brief Storage entity class
+ * 
+ */
 class storage_entity : public IEntity {
 private:
+    //! Global static ID for storage
     static entity_id __global_id;
 
+    //! Storage object ID
     entity_id _id = 0;
+    //! Storage's capacity
     unsigned int _capacity = 500000;
+    //! Storages's cargo collection
     QVector<cargo_entity> _cargo;
 
 public:
+    /**
+     * @brief Construct a new storage entity object
+     * 
+     */
     storage_entity();
+    /**
+     * @brief Construct a new storage entity object
+     * 
+     * @param capacity storage capacity
+     */
     storage_entity(unsigned int capacity);
 
+    /**
+     * @brief Get storage's ID
+     * 
+     * @return entity_id 
+     */
     entity_id id() const;
+    /**
+     * @brief Get storage's capacity
+     * 
+     * @return unsigned int 
+     */
     unsigned int capacity() const;
+    /**
+     * @brief Set storage's capacity
+     * 
+     * @param new_capacity new capacity
+     */
     void set_capacity(unsigned int new_capacity);
+    /**
+     * @brief Get immutable cargo collection
+     * 
+     * @return const QVector<cargo_entity> 
+     */
     const QVector<cargo_entity> cargo();
 
+    /**
+     * @brief Add cargo object to storage collection
+     * 
+     * @param object new cargo
+     * @param success operation success reference
+     */
     void add_cargo(cargo_entity object, bool &success);
+    /**
+     * @brief Get the cargo object
+     * 
+     * @param oid cargo ID
+     * @param found object found reference
+     * @return cargo_entity 
+     */
     cargo_entity get_cargo(entity_id oid, bool &found);
+    /**
+     * @brief Remove cargo from storage's collection
+     * 
+     * @param oid cargo ID
+     * @param success operation success reference
+     */
     void withdraw_cargo(entity_id oid, bool &success);
 
     void serialize(QDataStream &output);
     void deserialize(QDataStream &input);
+    /**
+     * @brief Sets GID of class
+     * 
+     * @param gid new class GID
+     */
     static void preloadGlobalId(entity_id gid);
+    /**
+     * @brief Returns GID of class
+     * 
+     * @return entity_id 
+     */
     static entity_id GID();
 };
 

sea_transport/entities/user_entity.h

@@ -8,33 +8,101 @@
 #include <QCryptographicHash>
 
 
+/**
+ * @brief Defines user account type
+ * 
+ */
 enum class UserRole {
-    ADMINISTRATOR, DISPATCHER, SKIPPER
+    ADMINISTRATOR,  //< User is administrator
+    DISPATCHER,     //< User is dispatcher
+    SKIPPER         //< User is skipper
 };
 
+/**
+ * @brief Class for user entity
+ * 
+ */
 class user_entity : public IEntity {
 private:
+    //! Global static ID for users
     static entity_id __global_id;
 
+    //! Object ID
     entity_id _id = 0;
+    //! User's login
     QString _login;
+    //! User's role
     UserRole _role;
+    //! User's password hash
     QByteArray _pwd_hash;
 
 public:
+    /**
+     * @brief Construct a new user entity object
+     * 
+     */
     user_entity();
+    /**
+     * @brief Construct a new user entity object
+     * 
+     * @param login new user's login 
+     * @param password new user's password
+     * @param role new user's account role
+     */
     user_entity(const QString &login, const QString &password, UserRole role);
 
+    /**
+     * @brief Get user's ID
+     * 
+     * @return entity_id 
+     */
     entity_id id() const;
+    /**
+     * @brief Get user's login
+     * 
+     * @return const QString 
+     */
     const QString login() const;
+    /**
+     * @brief Get user's account role
+     * 
+     * @return UserRole 
+     */
     UserRole role() const;
+    /**
+     * @brief Verify password
+     * 
+     * @param password password to be verified
+     * @return true passwords match
+     * @return false passwords do not mattch
+     */
     bool verify_password(const QString &password) const;
+    /**
+     * @brief Set user's password
+     * 
+     * @param new_password new password
+     */
     void set_password(const QString &new_password);
+    /**
+     * @brief Set user's role
+     * 
+     * @param new_role 
+     */
     void set_role(UserRole new_role);
 
     void serialize(QDataStream &output);
     void deserialize(QDataStream &input);
+    /**
+     * @brief Sets GID of class
+     * 
+     * @param gid new class GID
+     */
     static void preloadGlobalId(entity_id gid);
+    /**
+     * @brief Returns GID of class
+     * 
+     * @return entity_id 
+     */
     static entity_id GID();
 };
 

sea_transport/entities/vessel_entity.h

@@ -8,36 +8,121 @@
 #include <QRandomGenerator>
 
 
+/**
+ * @brief Vessel entity class
+ * 
+ */
 class vessel_entity : public IEntity {
 private:
+    //! Global static ID for vessels
     static entity_id __global_id;
 
+    //! Vessel ID
     entity_id _id = 0;
+    //! Skipper login
     QString _skipper;
+    //! Harbor ID
     entity_id _harbor_id;
+    //! Vessel capacity
     unsigned int _capacity = 50000;
+    //! Vessel's cargo collection
     QVector<cargo_entity> _cargo;
 
 public:
+    /**
+     * @brief Construct a new vessel entity object
+     * 
+     */
     vessel_entity();
+    /**
+     * @brief Construct a new vessel entity object
+     * 
+     * @param skipper skipper login
+     * @param harbor_id harbor ID
+     * @param capacity vessel capacity
+     */
     vessel_entity(QString skipper, entity_id harbor_id, unsigned int capacity);
 
     entity_id id() const;
+    /**
+     * @brief Get skipper login
+     * 
+     * @return QString 
+     */
     QString skipper() const;
+    /**
+     * @brief Set skipper login
+     * 
+     * @param new_skipper new skipper login
+     */
     void set_skipper(const QString &new_skipper);
+    /**
+     * @brief Get harbor ID
+     * 
+     * @return entity_id 
+     */
     entity_id harbor() const;
+    /**
+     * @brief Set harbor object
+     * 
+     * @param new_harbor new harbor ID
+     */
     void set_harbor(entity_id new_harbor);
+    /**
+     * @brief Get capacity of vessel
+     * 
+     * @return unsigned int 
+     */
     unsigned int capacity() const;
+    /**
+     * @brief Set capacity object
+     * 
+     * @param new_capacity new vessel capacity
+     */
     void set_capacity(unsigned int new_capacity);
+    /**
+     * @brief Get vessel's immutable cargo collection
+     * 
+     * @return const QVector<cargo_entity> 
+     */
     const QVector<cargo_entity> cargo();
 
+    /**
+     * @brief Add cargo to vessel's collection
+     * 
+     * @param object new cargo
+     * @param success operation success reference
+     */
     void add_cargo(cargo_entity object, bool &success);
+    /**
+     * @brief Get cargo object
+     * 
+     * @param oid cargo ID
+     * @param found object found reference
+     * @return cargo_entity 
+     */
     cargo_entity get_cargo(entity_id oid, bool &found);
+    /**
+     * @brief Remove cargo from vessel's collection
+     * 
+     * @param oid cargo ID
+     * @param success operation success reference
+     */
     void withdraw_cargo(entity_id oid, bool &success);
 
     void serialize(QDataStream &output);
     void deserialize(QDataStream &input);
+    /**
+     * @brief Sets GID of class
+     * 
+     * @param gid new class GID
+     */
     static void preloadGlobalId(entity_id gid);
+    /**
+     * @brief Returns GID of class
+     * 
+     * @return entity_id 
+     */
     static entity_id GID();
 };