fixed restore script internal value; improved hungarian notation; added doxygen comments

git-svn-id: https://svn.kvirc.de/svn/trunk/kvirc@5164 17fca916-40b9-46aa-a4ea-0a15b648b75c

5 files changed, 221 insertions, 134 deletions

diff --git a/src/kvirc/kvs/kvi_kvs_hash.cpp b/src/kvirc/kvs/kvi_kvs_hash.cpp
index c1f4ee73d..6ad87fe49 100644
--- a/src/kvirc/kvs/kvi_kvs_hash.cpp
+++ b/src/kvirc/kvs/kvi_kvs_hash.cpp
@@ -4,7 +4,7 @@
 //   Creation date : Tue 07 Oct 2003 01:22:37 by Szymon Stefanek
 //
 //   This file is part of the KVIrc IRC client distribution
-//   Copyright (C) 2003-2008 Szymon Stefanek <pragma at kvirc dot net>
+//   Copyright (C) 2003-2010 Szymon Stefanek <pragma at kvirc dot net>
 //
 //   This program is FREE software. You can redistribute it and/or
 //   modify it under the terms of the GNU General Public License
@@ -22,8 +22,6 @@
 //
 //=============================================================================
 
-
-
 #include "kvi_kvs_hash.h"
 
 KviKvsHash::KviKvsHash()
@@ -32,11 +30,11 @@ KviKvsHash::KviKvsHash()
 	m_pDict->setAutoDelete(true);
 }
 
-KviKvsHash::KviKvsHash(const KviKvsHash &h)
+KviKvsHash::KviKvsHash(const KviKvsHash & hash)
 {
 	m_pDict = new KviPointerHashTable<QString,KviKvsVariant>();
 	m_pDict->setAutoDelete(true);
-	KviPointerHashTableIterator<QString,KviKvsVariant> it(*(h.m_pDict));
+	KviPointerHashTableIterator<QString,KviKvsVariant> it(*(hash.m_pDict));
 	while(it.current())
 	{
 		m_pDict->replace(it.currentKey(),new KviKvsVariant(*(it.current())));
@@ -49,48 +47,53 @@ KviKvsHash::~KviKvsHash()
 	delete m_pDict;
 }
 
-void KviKvsHash::appendAsString(QString &szBuffer) const
+void KviKvsHash::appendAsString(QString & szBuffer) const
 {
 	KviPointerHashTableIterator<QString,KviKvsVariant> it(*m_pDict);
 	bool bNeedComma = false;
-	while(KviKvsVariant * s = it.current())
+	while(KviKvsVariant * pVariant = it.current())
 	{
-		if(bNeedComma)szBuffer.append(',');
-		else bNeedComma = true;
-		s->appendAsString(szBuffer);
+		if(bNeedComma)
+			szBuffer.append(',');
+		else
+			bNeedComma = true;
+		pVariant->appendAsString(szBuffer);
 		++it;
 	}
 }
 
-void KviKvsHash::serialize(QString& result)
+void KviKvsHash::serialize(QString & szResult)
 {
-	QString tmpBuffer;
-	result="{";
+	QString szTmp;
+	szResult = "{";
 	KviPointerHashTableIterator<QString,KviKvsVariant> it(*m_pDict);
 	bool bNeedComma = false;
-	while(KviKvsVariant * s = it.current())
+	while(KviKvsVariant * pVariant = it.current())
 	{
-		if(bNeedComma)result.append(',');
-		else bNeedComma = true;
+		if(bNeedComma)
+			szResult.append(',');
+		else
+			bNeedComma = true;
 
-		tmpBuffer = it.currentKey();
-		KviKvsVariant::serializeString(tmpBuffer);
-		result.append(tmpBuffer);
+		szTmp = it.currentKey();
+		KviKvsVariant::serializeString(szTmp);
+		szResult.append(szTmp);
 
-		result.append(":");
-		s->serialize(tmpBuffer);
-		result.append(tmpBuffer);
+		szResult.append(":");
+		pVariant->serialize(szTmp);
+		szResult.append(szTmp);
 
 		++it;
 	}
-	result.append('}');
+	szResult.append('}');
 }
 
-KviKvsVariant * KviKvsHash::get(const QString &szKey)
+KviKvsVariant * KviKvsHash::get(const QString & szKey)
 {
-	KviKvsVariant * v = m_pDict->find(szKey);
-	if(v)return v;
-	v = new KviKvsVariant();
-	m_pDict->replace(szKey,v);
-	return v;
+	KviKvsVariant * pVariant = m_pDict->find(szKey);
+	if(pVariant)
+		return pVariant;
+	pVariant = new KviKvsVariant();
+	m_pDict->replace(szKey,pVariant);
+	return pVariant;
 }
diff --git a/src/kvirc/kvs/kvi_kvs_hash.h b/src/kvirc/kvs/kvi_kvs_hash.h
index eaac081e6..8538269a6 100644
--- a/src/kvirc/kvs/kvi_kvs_hash.h
+++ b/src/kvirc/kvs/kvi_kvs_hash.h
@@ -6,7 +6,7 @@
 //   Creation date : Tue 07 Oct 2003 01:22:37 by Szymon Stefanek
 //
 //   This file is part of the KVIrc IRC client distribution
-//   Copyright (C) 2003-2008 Szymon Stefanek <pragma at kvirc dot net>
+//   Copyright (C) 2003-2010 Szymon Stefanek <pragma at kvirc dot net>
 //
 //   This program is FREE software. You can redistribute it and/or
 //   modify it under the terms of the GNU General Public License
@@ -24,41 +24,114 @@
 //
 //=============================================================================
 
-#include "kvi_settings.h"
+/**
+* \file kvi_kvs_hash.h
+* \author Szymon Stefanek
+* \brief Handling of hash data type in KVS
+*/
 
+#include "kvi_settings.h"
 #include "kvi_pointerhashtable.h"
 #include "kvi_qstring.h"
-
 #include "kvi_kvs_variant.h"
 #include "kvi_heapobject.h"
 
 typedef KVIRC_API_TYPEDEF KviPointerHashTableIterator<QString,KviKvsVariant> KviKvsHashIterator;
 
-// This class must not have virtual funcitons nor destructor
-// Otherwise it will happily crash on windows when it is
-// allocated in modules and destroyed anywhere else around...
+/**
+* \class KviKvsHash
+* \brief This class defines a new data type which contains hash data
+* \warning This class must not have virtual functions nor destructor. Otherwise it will happily
+* crash on windows when it is allocated in modules and destroyed anywhere else around
+*/
 class KVIRC_API KviKvsHash : public KviHeapObject
 {
 public:
+	/**
+	* \brief Constructs the hash data
+	* \return KviKvsHash
+	*/
 	KviKvsHash();
-	KviKvsHash(const KviKvsHash &h);
+
+	/**
+	* \brief Constructs the hash data
+	* 
+	* This is a carbon copy
+	* \param array The hash to copy from
+	* \return KviKvsHash
+	*/
+	KviKvsHash(const KviKvsHash & hash);
+
+	/**
+	* \brief Destroys the array data
+	*/
 	~KviKvsHash();
 protected:
 	KviPointerHashTable<QString,KviKvsVariant> * m_pDict;
 public:
-	void unset(const QString &szKey){ m_pDict->remove(szKey); };
-	void set(const QString &szKey,KviKvsVariant * pVal){ m_pDict->replace(szKey,pVal); };
-	KviKvsVariant * find(const QString &szKey) const { return m_pDict->find(szKey); };
-	KviKvsVariant * get(const QString &szKey);
+	/**
+	* \brief Unsets an element from the hash
+	* \param szKey The key of the element to unset
+	* \return void
+	*/
+	void unset(const QString & szKey){ m_pDict->remove(szKey); };
 
+	/**
+	* \brief Sets an element into the hash
+	* \param szKey The key of the element to set
+	* \param pVal The value to set
+	* \return void
+	*/
+	void set(const QString & szKey, KviKvsVariant * pVal){ m_pDict->replace(szKey,pVal); };
+
+	/**
+	* \brief Returns the element associated to the given key
+	* \param szKey The key of the element to retrieve
+	* \return KviKvsVariant *
+	*/
+	KviKvsVariant * find(const QString & szKey) const { return m_pDict->find(szKey); };
+
+	/**
+	* \brief Returns the element associated to the given key
+	* 
+	* If the element doesn't exists, it returns an empty element. If the index is out of
+	* hash bounds, it increases the hash size, fillin the hash in with empty strings.
+	* \param szKey The key of the element to retrieve
+	* \return KviKvsVariant *
+	*/
+	KviKvsVariant * get(const QString & szKey);
+
+	/**
+	* \brief Returns true if the hash is empty
+	* \return bool
+	*/
 	bool isEmpty() const { return m_pDict->isEmpty(); };
+
+	/**
+	* \brief Returns the size of the hash
+	* \return kvs_uint_t
+	*/
 	kvs_uint_t size() const { return m_pDict->count(); };
 
-	void appendAsString(QString &szBuffer) const;
+	/**
+	* \brief Appends data to the hash converting it into a string
+	* \param szBuffer The string to append
+	* \return void
+	*/
+	void appendAsString(QString & szBuffer) const;
 
+	/**
+	* \brief Returns the internal dictionary of the hash
+	* \return const KviPointerHashTable<QString,KviKvsVariant> *
+	*/
 	const KviPointerHashTable<QString,KviKvsVariant> * dict(){ return m_pDict; };
 
-	void serialize(QString& result);
+	/**
+	* \brief Serializes the hash to a given buffer
+	* \param szResult The buffer to store
+	* \return void
+	*/
+	void serialize(QString & szResult);
 };
 
-#endif //!_KVI_KVS_HASH_H_
+#endif // _KVI_KVS_HASH_H_
diff --git a/src/kvirc/kvs/kvi_kvs_script.h b/src/kvirc/kvs/kvi_kvs_script.h
index 281fb2fb4..6e9ca7524 100644
--- a/src/kvirc/kvs/kvi_kvs_script.h
+++ b/src/kvirc/kvs/kvi_kvs_script.h
@@ -6,7 +6,7 @@
 //   Creation date : Thu 25 Sep 2003 05.12 CEST by Szymon Stefanek
 //
 //   This file is part of the KVirc irc client distribution
-//   Copyright (C) 2003-2008 Szymon Stefanek (pragma at kvirc dot net)
+//   Copyright (C) 2003-2010 Szymon Stefanek (pragma at kvirc dot net)
 //
 //   This program is FREE software. You can redistribute it and/or
 //   modify it under the terms of the GNU General Public License
@@ -52,9 +52,6 @@ class KviKvsRunTimeContext;
 	#undef Success
 #endif
 
-
-
-
 /**
 * \class KviKvsScript
 * \brief The KVIrc Script class
@@ -67,32 +64,35 @@ class KVIRC_API KviKvsScript : public KviHeapObject
 public:
 	/**
 	* \enum RunStatus
+	* \brief Holds the run status of the script
 	*/
 	enum RunStatus {
-		Error = 0, /**< The script returned an error */
-		Success = 1, /**< The script ran successfully */
-		HaltEncountered = 2 /**< The script ran successfully and halt was encountered */
+		Error           = 0,   /**< The script returned an error */
+		Success         = 1,   /**< The script ran successfully */
+		HaltEncountered = 2    /**< The script ran successfully and halt was encountered */
 	};
 
 	/**
 	* \enum ScriptType
+	* \brief Holds the type of the script
 	*/
 	enum ScriptType {
-		InstructionList, /**< The most common script type: a sequence of instructions */
-		Expression, /**< An expression to be evaluated as in a $() call (pRetVal should be always set!) */
-		Parameter /**< A parameter to be evaluated (pRetVal should be always set!) */
+		InstructionList,   /**< The most common script type: a sequence of instructions */
+		Expression,        /**< An expression to be evaluated as in a $() call (pRetVal should be always set!) */
+		Parameter          /**< A parameter to be evaluated (pRetVal should be always set!) */
 	};
 
 	/**
 	* \enum RunFlags
+	* \brief Holds the run flags of the script
 	*/
 	enum RunFlags {
-		PreserveParams = 1, /**< Do not delete the eventual parameters passed (only execute() and run()) */
+		PreserveParams = 1,   /**< Do not delete the eventual parameters passed (only execute() and run()) */
 		// FIXME: This should be a global option, eventually
-		AssumeLocals = 2, /**< Assume that the variables are local unless explicitly declared (flag used only for parse()) */
+		AssumeLocals   = 2,   /**< Assume that the variables are local unless explicitly declared (flag used only for parse()) */
 		// FIXME: This should be a global option, eventually
-		Pedantic = 4, /**< Be more pedantic: spit more warnings and sometimes more errors */
-		Quiet = 8 /**< Don't print any errors */
+		Pedantic       = 4,   /**< Be more pedantic: spit more warnings and sometimes more errors */
+		Quiet          = 8    /**< Don't print any errors */
 	};
 public:
 	/**
diff --git a/src/kvirc/ui/kvi_input_editor.cpp b/src/kvirc/ui/kvi_input_editor.cpp
index fda9431c6..84cd09b83 100644
--- a/src/kvirc/ui/kvi_input_editor.cpp
+++ b/src/kvirc/ui/kvi_input_editor.cpp
@@ -1701,7 +1701,7 @@ void KviInputEditor::replaceWordBeforeCursor(const QString & szWord, const QStri
 		repaintWithCursorOn();
 }
 
-void KviInputEditor::standardNickCompletionInsertCompletedText(const QString &szReplacedWord,const QString &szCompletedText,bool bFirstWordInLine,bool bInCommand)
+void KviInputEditor::standardNickCompletionInsertCompletedText(const QString & szReplacedWord, const QString & szCompletedText, bool bFirstWordInLine, bool bInCommand)
 {
 	QString szBuffer = szCompletedText;
 
diff --git a/src/kvirc/ui/kvi_input_editor.h b/src/kvirc/ui/kvi_input_editor.h
index e3d9ee4a5..42fd0899d 100644
--- a/src/kvirc/ui/kvi_input_editor.h
+++ b/src/kvirc/ui/kvi_input_editor.h
@@ -150,103 +150,108 @@ protected:
 	KviTalPopupMenu         * m_pIconMenu;
 	bool                      m_bReadOnly;
 
+	/**
+	* \class EditCommand
+	* \brief Holds the command used in the {un,re}do operations
+	*/
 	class EditCommand
 	{
 	public:
+		/**
+		* \enum Type
+		* \brief Defines the type of the command
+		*/
 		enum Type
 		{
-			///
-			/// Text insertion. Has text, position previous to the insert and length of the insert.
-			///
-			InsertText,
-			///
-			/// Text removal, Has text, position previous to the removal and length of the removed data.
-			///
-			RemoveText
+			InsertText,   /**< Text insertion. Has text, position previous to the insert and length of the insert */
+			RemoveText    /**< Text removal, Has text, position previous to the removal and length of the removed data */
 		};
 	private:
-		///
-		/// the type of the command
-		///
+		/**
+		* \var m_eType
+		* \brief The type of the command
+		*/
 		Type m_eType;
 
-		///
-		/// the text of the command
-		///
+		/**
+		* \var m_szText
+		* \brief The text of the command
+		*/
 		QString m_szText;
 
-		///
-		/// the start position
-		///
+		/**
+		* \var m_iStartPosition
+		* \brief The start position
+		*/
 		int m_iStartPosition;
-
 	public:
-		EditCommand(Type eType,const QString &szText,int iStartPosition)
-			: m_eType(eType), m_szText(szText), m_iStartPosition(iStartPosition)
+		/**
+		* \brief Contructs the command object
+		* \param eType The type of the command
+		* \param szText The text of the command
+		* \param iStartPosition The start position of the command
+		* \return EditCommand
+		*/
+		EditCommand(Type eType, const QString & szText, int iStartPosition)
+		: m_eType(eType), m_szText(szText), m_iStartPosition(iStartPosition)
 		{
 		}
 
-		///
-		/// Sets the start position
-		///
-		void setStartPosition(int iStartPosition)
-		{
-			m_iStartPosition = iStartPosition;
-		}
-	
-		///
-		/// Returns the start position
-		///
-		int startPosition() const
-		{
-			return m_iStartPosition;
-		}
+		/**
+		* \brief Sets the start position
+		* \param iStartPosition The position
+		* \return void
+		*/
+		void setStartPosition(int iStartPosition){ m_iStartPosition = iStartPosition; }
 	
+		/**
+		* \brief Returns the start position
+		* \return int
+		*/
+		int startPosition() const { return m_iStartPosition; }
 
-		///
-		/// Sets the text of the command
-		///
-		void setText(const QString &szText)
-		{
-			m_szText = szText;
-		}
-	
-		///
-		/// Returns the text of the command
-		///
-		const QString & text() const
-		{
-			return m_szText;
-		}
+		/**
+		* \brief Sets the text of the command
+		* \param szText The text to set
+		*/
+		void setText(const QString & szText){ m_szText = szText; }
 	
+		/**
+		* \brief Returns the text of the command
+		* \return const QString &
+		*/
+		const QString & text() const { return m_szText; }
 
-		///
-		/// Sets the type of the command
-		///
-		void setType(const Type &eType)
-		{
-			m_eType = eType;
-		}
+		/**
+		* \brief Sets the type of the command
+		* \param eType The type of the command
+		* \return void
+		*/
+		void setType(const Type & eType){ m_eType = eType; }
 	
-		///
-		/// Returns the type of the command
-		///
-		const Type & type() const
-		{
-			return m_eType;
-		}
+		/**
+		* \brief Returns the type of the command
+		* \return const Type &
+		*/
+		const Type & type() const { return m_eType; }
 	};
 
-	///
-	/// The undo stack. Contains owned pointers and has autodelete set to true.
-	/// The most recent command is at the end. Null when no undo is available.
-	///
+	/**
+	* \var m_pUndoStack
+	* \brief The undo stack.
+	* 
+	* Contains owned pointers and has autodelete set to true. The most recent command
+	* is at the end. Null when no undo is available.
+	*/
 	KviPointerList<EditCommand> * m_pUndoStack;
 
-	///
-	/// The redo stack. Contains owned pointers and has autodelete set to true.
-	/// The most recently undone command is at the end. Null when no redo is available.
-	///
+	/**
+	* \var m_pRedoStack
+	* \brief The redo stack.
+	* 
+	* Contains owned pointers and has autodelete set to true. The most recently undone
+	* command is at the end. Null when no redo is available.
+	*/
 	KviPointerList<EditCommand> * m_pRedoStack;
 
 public:
@@ -480,15 +485,20 @@ private:
 	* \param bAddMask Whether to complete with the mask of the nickname
 	* \param szWord The nickname to complete
 	* \param bFirstWordInLine Whether the word to complete is the first word in the text line (so the suffix from option panel is added)
-	* \param bInCommand true if the completion happens inside a kvs command (and thus the completed word should be kvs-escaped)
+	* \param bInCommand Whether the completion happens inside a kvs command (and thus the completed word should be kvs-escaped)
 	* \return void
 	*/
 	void standardNickCompletion(bool bAddMask, QString & szWord, bool bFirstWordInLine, bool bInCommand);
 
 	/**
-	* Internal helper for standardNickCompletion()
+	* \brief Internal helper for standardNickCompletion()
+	* \param szReplacedWord The word replaced before the cursor
+	* \param szCompletedText The text to be completed
+	* \param bFirstWordInLine Whether the word to complete is the first word in the text line (so the suffix from option panel is added)
+	* \param bInCommand Whether the completion happens inside a kvs command (and thus the completed word should be kvs-escaped)
+	* \return void
 	*/
-	void standardNickCompletionInsertCompletedText(const QString &szReplacedWord,const QString &szCompletedText,bool bFirstWordInLine,bool bInCommand);
+	void standardNickCompletionInsertCompletedText(const QString & szReplacedWord, const QString & szCompletedText, bool bFirstWordInLine, bool bInCommand);
 
 	/**
 	* \brief Moves the cursor one character to the right
@@ -518,7 +528,7 @@ private:
 
 	/**
 	* \brief Inserts one action in the undo stack
-	* \param cmd The command struct representing the action
+	* \param pCommand The command representing the action
 	* \return void
 	*/
 	void addUndo(EditCommand * pCommand);
@@ -563,6 +573,7 @@ public slots:
 	*
 	* If the system supports the mouse clipboard, the text will be
 	* copied there
+	* \param bDonNotCopyToClipboard Whether to copy the text to the system clipboard
 	* \return void
 	*/
 	void copyToSelection(bool bDonNotCopyToClipboard = true);