Docs

include/transport/config.h

@@ -38,18 +38,38 @@ namespace Transport {
 
 typedef boost::program_options::variables_map Variables;
 
-/// Class used to load.
+/// Represents config file.
+
+/// It's used to load config file and allows others parts of libtransport to be configured
+/// properly. Config files are text files which use "ini" format. Variables are divided into multiple
+/// sections. Every class is configurable with some variables which change its behavior. Check particular
+/// class documentation to get a list of all relevant variables for that class.
 class Config {
 	public:
+		/// Constructor.
 		Config() {}
+
+		/// Destructor
 		virtual ~Config() {}
+
+		/// Loads data from config file. You can pass your extra options which will be recognized by
+		/// the parser using opts parameter.
+		/// \param configfile path to config file
+		/// \param opts extra options which will be recognized by a parser
 		bool load(const std::string &configfile, boost::program_options::options_description &opts);
+
+		/// Loads data from config file. This function loads only config variables needed by libtransport.
+		/// \see load(const std::string &, boost::program_options::options_description &)
+		/// \param configfile path to config file
 		bool load(const std::string &configfile);
 
+		/// Returns value of variable defined by key. For variables in sections you can use "section.variable" key format.
+		/// \param key config variable name
 		const boost::program_options::variable_value &operator[] (const std::string &key) {
 			return m_variables[key];
 		}
 
+		/// This signal is emitted when config is loaded/reloaded.
 		boost::signal<void ()> onConfigReloaded;
 	
 	private:

include/transport/sqlite3backend.h

@@ -29,20 +29,54 @@
 
 namespace Transport {
 
+/// Used to store transport data into SQLite3 database.
 class SQLite3Backend : public StorageBackend
 {
 	public:
+		/// Creates new SQLite3Backend instance.
+		/// \param config cofiguration, this class uses following Config values:
+		/// 	- database.database - path to SQLite3 database file, database file is created automatically
+		/// 	- service.prefix - prefix for tables created by createDatabase method
 		SQLite3Backend(Config *config);
+
+		/// Destructor.
 		~SQLite3Backend();
 
+		/// Connects to the database and creates it if it's needed. This method call createDatabase() function
+		/// automatically.
+		/// \return true if database is opened successfully.
 		bool connect();
+
+		/// Creates database structure.
+		/// \see connect()
+		/// \return true if database structure has been created successfully. Note that it returns True also if database structure
+		/// already exists.
 		bool createDatabase();
 
+		/// Stores user into database.
+		/// \param user user struct containing all information about user which have to be stored
 		void setUser(const UserInfo &user);
-		bool getUser(const std::string &barejid, UserInfo &user);
-		void setUserOnline(long id, bool online);
-		void removeUser(long id);
 
+		/// Gets user data from database and stores them into user reference.
+		/// \param barejid barejid of user
+		/// \param user UserInfo object where user data will be stored
+		/// \return true if user has been found in database
+		bool getUser(const std::string &barejid, UserInfo &user);
+
+		/// Changes users online state variable in database.
+		/// \param id id of user - UserInfo.id
+		/// \param online online state
+		void setUserOnline(long id, bool online);
+
+		/// Removes user and all connected data from database.
+		/// \param id id of user - UserInfo.id
+		/// \return true if user has been found in database and removed
+		bool removeUser(long id);
+
+		/// Returns JIDs of all buddies in user's roster.
+		/// \param id id of user - UserInfo.id
+		/// \param roster string list used to store user's roster
+		/// \return true if user has been found in database and roster has been fetched
 		bool getBuddies(long id, std::list<std::string> &roster);
 
 	private:

include/transport/storagebackend.h

@@ -25,31 +25,46 @@
 
 namespace Transport {
 
+/// Represents all data needed to be stored in database.
 struct UserInfo {
-	long id;
-	std::string jid;
-	std::string uin;
-	std::string password;
-	std::string language;
-	std::string encoding;
-	bool vip;
+	long id;				///< id of user used as primary key in database
+	std::string jid;		///< barejid of XMPP user
+	std::string uin;		///< legacy network username
+	std::string password;	///< password for legacy network
+	std::string language;	///< user's preferred language
+	std::string encoding;	///< user's preferred encoding
+	bool vip;				///< true if user is VIP
 };
 
+/// Abstract class defining storage backends.
 class StorageBackend
 {
 	public:
+		/// Virtual desctructor.
 		virtual ~StorageBackend() {}
 
+		/// connect
 		virtual bool connect() = 0;
+
+		/// createDatabase
 		virtual bool createDatabase() = 0;
 
+		/// setUser
 		virtual void setUser(const UserInfo &user) = 0;
-		virtual bool getUser(const std::string &barejid, UserInfo &user) = 0;
-		virtual void setUserOnline(long id, bool online) = 0;
-		virtual void removeUser(long id) = 0;
 
+		/// getuser
+		virtual bool getUser(const std::string &barejid, UserInfo &user) = 0;
+
+		/// setUserOnline
+		virtual void setUserOnline(long id, bool online) = 0;
+
+		/// removeUser
+		virtual bool removeUser(long id) = 0;
+
+		/// getBuddies
 		virtual bool getBuddies(long id, std::list<std::string> &roster) = 0;
 
+		/// onStorageError
 		boost::signal<void (const std::string &statement, const std::string &error)> onStorageError;
 
 };

include/transport/transport.h

@@ -82,10 +82,25 @@ namespace Transport {
 			/// \return Jabber ID of this transport
 			Swift::JID &getJID() { return m_jid; }
 
-			boost::signal<void (const Swift::ComponentError&)> onConnectionError;
+			/// This signal is emitted when server disconnects the transport because of some error.
+			/// \param error disconnection error
+			boost::signal<void (const Swift::ComponentError &error)> onConnectionError;
+
+			/// This signal is emitted when transport successfully connects the server.
 			boost::signal<void ()> onConnected;
-			boost::signal<void (const std::string &)> onXMLOut;
-			boost::signal<void (const std::string &)> onXMLIn;
+
+			/// This signal is emitted when XML stanza is sent to server.
+			/// \param xml xml stanza
+			boost::signal<void (const std::string &xml)> onXMLOut;
+
+			/// This signal is emitted when XML stanza is received from server.
+			/// \param xml xml stanza
+			boost::signal<void (const std::string &xml)> onXMLIn;
+
+			/// This signal is emitted when presence from XMPP user (for example "user@domain.tld")
+			/// is received. It's emitted only for presences addressed to transport itself
+			/// (for example to="j2j.domain.tld").
+			/// \param presence presence data
 			boost::signal<void (Swift::Presence::ref presence)> onUserPresenceReceived;
 
 		private:

src/sqlite3backend.cpp

@@ -131,7 +131,7 @@ bool SQLite3Backend::getBuddies(long id, std::list<std::string> &roster) {
 	return true;
 }
 
-void SQLite3Backend::removeUser(long id) {
+bool SQLite3Backend::removeUser(long id) {
 	
 }