Some code scrubing

Add doxygen documentation for classes and methods
Delete useless comments.
Add include guards where missing.
Delete some useless typedef.

Change-Id: I9bba16560790239d7775fcd40981465e70e5d437

10 files changed, 96 insertions, 103 deletions

diff --git a/l10ntools/inc/cfgmerge.hxx b/l10ntools/inc/cfgmerge.hxx
index 9710008707aa..03addd1ada04 100644
--- a/l10ntools/inc/cfgmerge.hxx
+++ b/l10ntools/inc/cfgmerge.hxx
@@ -64,12 +64,10 @@ public:
 // class CfgStack
 //
 
-typedef std::vector< CfgStackData* > CfgStackList;
-
 class CfgStack
 {
 private:
-    CfgStackList maList;
+    std::vector< CfgStackData* > maList;
 
 public:
     CfgStack() {}
@@ -92,10 +90,7 @@ public:
     size_t size() const { return maList.size(); }
 };
 
-//
-// class CfgParser
-//
-
+/// Parser for *.xcu files
 class CfgParser
 {
 protected:
@@ -136,10 +131,7 @@ public:
     int Execute( int nToken, char * pToken );
 };
 
-//
-// class CfgExport
-//
-
+/// Export strings from *.xcu files
 class CfgExport : public CfgParser
 {
 private:
@@ -162,10 +154,7 @@ public:
     ~CfgExport();
 };
 
-//
-// class CfgMerge
-//
-
+/// Merge strings to *.xcu files
 class CfgMerge : public CfgParser
 {
 private:
diff --git a/l10ntools/inc/common.hxx b/l10ntools/inc/common.hxx
index 93f2d008cb82..5a12bbbbebe4 100644
--- a/l10ntools/inc/common.hxx
+++ b/l10ntools/inc/common.hxx
@@ -7,7 +7,7 @@
  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
  */
 
-/// Methods used by all of executables
+// Methods used by all of executables
 
 #ifndef INCLUDED_L10NTOOLS_SOURCE_COMMON_HXX
 #define INCLUDED_L10NTOOLS_SOURCE_COMMON_HXX
@@ -20,7 +20,7 @@
 
 namespace common {
 
-//result type of handleArguments()
+/// Result type of handleArguments()
 struct HandledArgs
 {
     OString m_sInputFile;
@@ -37,10 +37,13 @@ struct HandledArgs
     {}
 };
 
+/// Handle command line parameters
 bool handleArguments(int argc, char * argv[], HandledArgs& o_aHandledArgs);
 
+/// Write out a help about usage
 void writeUsage(const OString& rName, const OString& rFileType);
 
+/// Write out a PoEntry with attention to excaptions
 void writePoEntry(
     const OString& rExecutable, PoOfstream& rPoStream, const OString& rSourceFile,
     const OString& rResType, const OString& rGroupId, const OString& rLocalId,
diff --git a/l10ntools/inc/export.hxx b/l10ntools/inc/export.hxx
index a7f8ea126583..d23cc6f29e5e 100644
--- a/l10ntools/inc/export.hxx
+++ b/l10ntools/inc/export.hxx
@@ -30,9 +30,9 @@
 #include <osl/file.h>
 
 #include <boost/unordered_map.hpp>
-#include <iterator> /* std::iterator*/
-#include <set>      /* std::set*/
-#include <vector>   /* std::vector*/
+#include <iterator>
+#include <set>
+#include <vector>
 #include <queue>
 #include <string>
 
@@ -44,7 +44,6 @@
 #define NO_TRANSLATE_ISO        "x-no-translate"
 
 class MergeEntrys;
-class MergeData;
 
 typedef boost::unordered_map<OString, OString, OStringHash>
     OStringHashMap;
@@ -56,17 +55,18 @@ typedef boost::unordered_map<OString, bool, OStringHash>
 #define X_COMMENT "x-comment"
 #define LIST_REFID  "LIST_REFID"
 
-typedef OStringHashMap ExportListEntry;
-typedef ::std::vector< ExportListEntry* > ExportListBase;
-
 //
 // class ExportList
 //
 
+typedef OStringHashMap ExportListEntry;
+
+
+/// Container for parse different types of string lists
 class ExportList
 {
 private:
-    ExportListBase maList;
+    std::vector< ExportListEntry* > maList;
     std::size_t nSourceLanguageListEntryCount;
 
 public:
@@ -85,13 +85,9 @@ public:
 #define REFID_NONE 0xFFFF
 
 //
-// struct ResData
+// class ResData
 //
 
-/******************************************************************************
-* Purpose: holds mandatory data to export a single res (used with ResStack)
-******************************************************************************/
-
 #define ID_LEVEL_NULL       0x0000
 #define ID_LEVEL_AUTOID     0x0001
 #define ID_LEVEL_TEXT       0x0002
@@ -100,6 +96,8 @@ public:
 #define ID_LEVEL_IDENTIFIER 0x0005
 #define ID_LEVEL_LISTINDEX  0x0006
 
+
+/// Purpose: holds mandatory data to export a single res (used with ResStack)
 class ResData
 {
 public:
@@ -146,10 +144,6 @@ public:
 // class Export
 //
 
-/******************************************************************************
-* Purpose: syntax check and export of *.src, called from lexer
-******************************************************************************/
-
 #define LIST_NON                    0x0000
 #define LIST_STRING                 0x0001
 #define LIST_FILTER                 0x0002
@@ -165,9 +159,9 @@ public:
 #define MERGE_MODE_LIST             0x0001
 
 typedef ::std::vector< ResData* > ResStack;
-// forwards
 class ParserQueue;
 
+/// Purpose: syntax check and export of *.src, called from lexer
 class Export
 {
 private:
@@ -178,12 +172,12 @@ private:
 
     } aOutput;
 
-    ResStack aResStack;                 // stack for parsing recursive
+    ResStack aResStack;                 ///< stack for parsing recursive
 
     sal_Bool bDefine;                       // cur. res. in a define?
-    sal_Bool bNextMustBeDefineEOL;          // define but no \ at lineend
+    sal_Bool bNextMustBeDefineEOL;          ///< define but no \ at lineend
     std::size_t nLevel; // res. recursiv? how deep?
-    sal_uInt16 nList;                       // cur. res. is String- or FilterList
+    sal_uInt16 nList;                       ///< cur. res. is List
     OString m_sListLang;
     std::size_t nListIndex;
     std::size_t nListLevel;
@@ -199,13 +193,13 @@ private:
 
     std::vector<OString> aLanguages;
 
-    sal_Bool WriteData( ResData *pResData, sal_Bool bCreateNew = sal_False );// called befor dest. cur ResData
+    sal_Bool WriteData( ResData *pResData, sal_Bool bCreateNew = sal_False ); ///< called befor dest. cur ResData
     sal_Bool WriteExportList( ResData *pResData, ExportList *pExportList,
                         const OString &rTyp, sal_Bool bCreateNew = sal_False );
 
     OString MergePairedList( OString const & sLine , OString const & sText );
 
-    OString FullId();                    // creates cur. GID
+    OString FullId();                    ///< creates cur. GID
 
     OString GetPairedListID(const OString & rText);
     OString GetPairedListString(const OString& rText);
@@ -237,7 +231,7 @@ public:
     ~Export();
 
     void Init();
-    int Execute( int nToken, const char * pToken ); // called from lexer
+    int Execute( int nToken, const char * pToken ); ///< called from lexer
     void SetError() { bError = sal_True; }
     sal_Bool GetError() { return bError; }
     ParserQueue* pParseQueue; // public!!
@@ -248,10 +242,7 @@ public:
 // class MergeEntrys
 //
 
-/**
- * Purpose: holds information of data to merge
- */
-
+/// Purpose: holds information of data to merge
 class MergeEntrys
 {
 friend class MergeDataFile;
@@ -286,6 +277,12 @@ public:
 
 };
 
+//
+// class MergeDataHashMap
+//
+
+class MergeData;
+
 /** Container for MergeData
 
   This class is an HashMap with a hidden insertion
@@ -331,12 +328,7 @@ class MergeDataHashMap
 // class MergeData
 //
 
-/******************************************************************************
-* Purpose: holds information of data to merge (one resource)
-******************************************************************************/
-
-class MergeDataFile;
-
+/// Purpose: holds information of data to merge (one resource)
 class MergeData
 {
     friend class MergeDataHashMap;
@@ -361,10 +353,7 @@ public:
 // class MergeDataFile
 //
 
-/******************************************************************************
-* Purpose: holds information of data to merge
-******************************************************************************/
-
+/// Purpose: holds information of data to merge, read from PO file
 class MergeDataFile
 {
     private:
@@ -421,11 +410,8 @@ public:
 
     void Close();
 private:
-    // Future / Next
     std::queue<QueueEntry>* aQueueNext;
-    // Current
     std::queue<QueueEntry>* aQueueCur;
-    // Ref
     std::queue<QueueEntry>* aQref;
 
     Export& aExport;
@@ -434,6 +420,6 @@ private:
     inline void Pop( std::queue<QueueEntry>& aQueue );
 
 };
-#endif
+#endif // _EXPORT_HXX
 
 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */
diff --git a/l10ntools/inc/helper.hxx b/l10ntools/inc/helper.hxx
index 9ec399647c49..936010343f8f 100644
--- a/l10ntools/inc/helper.hxx
+++ b/l10ntools/inc/helper.hxx
@@ -7,7 +7,7 @@
  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
  */
 
-/// Helper methods to work with xml files
+// Helper string methods
 
 #ifndef INCLUDED_L10NTOOLS_SOURCE_HELPER_HXX
 #define INCLUDED_L10NTOOLS_SOURCE_HELPER_HXX
@@ -25,17 +25,22 @@
 
 namespace helper {
 
+/// Escape all given character in the text
 OString escapeAll(
     const OString& rText, const OString& rUnEscaped, const OString& rEscaped );
+/// Unescape all given character in the text
 OString unEscapeAll(
     const OString& rText, const OString& rEscaped, const OString& rUnEscaped  );
 
+/// Convert special characters to XML entity references
 OString QuotHTML( const OString &rString );
+/// Convert XML entity references to single characters
 OString UnQuotHTML( const OString& rString );
 
+/// Check whether text is a valid XML expression
 bool isWellFormedXML( OString const & text );
 
-//Convert xmlChar* to OString
+/// Convert xmlChar* to OString
 OString xmlStrToOString( const xmlChar* pString );
 
 }
diff --git a/l10ntools/inc/lngmerge.hxx b/l10ntools/inc/lngmerge.hxx
index 0f98eac2dc9c..968bb3e4cd12 100644
--- a/l10ntools/inc/lngmerge.hxx
+++ b/l10ntools/inc/lngmerge.hxx
@@ -17,6 +17,9 @@
  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  */
 
+#ifndef LNGMERGE_INCLUDED
+#define LNGMERGE_INCLUDED
+
 #include "sal/config.h"
 
 #include <iosfwd>
@@ -30,10 +33,13 @@ typedef std::vector< OString* > LngLineList;
 #define LNG_OK              0x0000
 #define LNG_COULD_NOT_OPEN  0x0001
 
-//
-// class LngParser
-//
 
+/**
+  Class for localization of *.ulf files
+
+  Parse *.ulf files, extract translatable strings
+  and merge translated strings.
+*/
 class LngParser
 {
 private:
@@ -58,4 +64,6 @@ public:
          const OString &rLanguage );
 };
 
+#endif // LNGMERGE_INCLUDED
+
 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */
diff --git a/l10ntools/inc/po.hxx b/l10ntools/inc/po.hxx
index 603727d8583b..1ec3b33e7861 100755
--- a/l10ntools/inc/po.hxx
+++ b/l10ntools/inc/po.hxx
@@ -52,16 +52,16 @@ public:
                     PoEntry( const PoEntry& rPo );
     PoEntry&        operator=( const PoEntry& rPo );
 
-    OString         getSourceFile() const;
+    OString         getSourceFile() const;      ///< Get name of file from which entry is extracted
     OString         getGroupId() const;
     OString         getLocalId() const;
-    OString         getResourceType() const;
-    TYPE            getType() const;
+    OString         getResourceType() const;    ///< Get the type of component from which entry is extracted
+    TYPE            getType() const;            ///< Get the type of entry
     OString         getMsgId() const;
     OString         getMsgStr() const;
     bool            isFuzzy() const;
-    OString         getKeyId() const;
 
+    /// Check whether po-s belong to the same localization component
     static bool     IsInSameComp(const PoEntry& rPo1,const PoEntry& rPo2);
     static OString  genKeyId(const OString& rGenerator);
 
@@ -85,7 +85,7 @@ public:
     friend class PoOfstream;
     friend class PoIfstream;
 
-                    PoHeader( const OString& rExtSrc );
+                    PoHeader( const OString& rExtSrc ); ///< Template Constructor
                     ~PoHeader();
 };
 
diff --git a/l10ntools/inc/propmerge.hxx b/l10ntools/inc/propmerge.hxx
index b6e2a0b3b85f..b4289655ecd8 100644
--- a/l10ntools/inc/propmerge.hxx
+++ b/l10ntools/inc/propmerge.hxx
@@ -13,11 +13,13 @@
 #include <rtl/string.hxx>
 #include <vector>
 
-/** Class for properties localization
+/**
+  Class for localization of *.properties files
 
-    Parse *.properties files, extract translatable strings
-    and merge translated strings.
+  Parse *.properties files, extract translatable strings
+  and merge translated strings.
 */
+
 class PropParser
 {
 private:
@@ -37,5 +39,5 @@ public:
     void Merge( const OString &rMergeSrc, const OString &rDestinationFile );
 };
 
-#endif //_PROPMERGE_INCLUDED
+#endif // _PROPMERGE_INCLUDED
 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */
diff --git a/l10ntools/inc/treemerge.hxx b/l10ntools/inc/treemerge.hxx
index d3d15af0b3dc..c98b77b07ec5 100644
--- a/l10ntools/inc/treemerge.hxx
+++ b/l10ntools/inc/treemerge.hxx
@@ -14,11 +14,12 @@
 #include <rtl/string.hxx>
 #include <vector>
 
-/** Class for tree localization
+/**
+  Class for localization of *.tree files
 
-    Parse *.tree files, extract translatable strings,
-    merge translated strings and update reference and title
-    of referred help files.
+  Parse *.tree files, extract translatable strings,
+  merge translated strings and update reference and title
+  of referred help files.
 */
 class TreeParser
 {
@@ -28,16 +29,19 @@ private:
     bool m_bIsInitialized;
 
 public:
-    TreeParser(
-        const OString& rInputFile, const OString& rLang );
+    /// Parse tree file
+    TreeParser( const OString& rInputFile, const OString& rLang );
     ~TreeParser();
 
     bool isInitialized() const { return m_bIsInitialized; }
+    /// Export strings
     void Extract( const OString& rPOFile );
+    /// Merge strings to tree file and update reference to help files(xhp)
     void Merge(
         const OString &rMergeSrc, const OString &rDestinationFile,
         const OString &rXhpRoot );
 };
 
-#endif //_TREEMERGE_INCLUDED
+#endif // _TREEMERGE_INCLUDED
+
 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */
diff --git a/l10ntools/inc/xmlparse.hxx b/l10ntools/inc/xmlparse.hxx
index 8daf546fcc7f..62c24b63f7ae 100644
--- a/l10ntools/inc/xmlparse.hxx
+++ b/l10ntools/inc/xmlparse.hxx
@@ -123,9 +123,10 @@ typedef std::vector< XMLChildNode* > XMLChildNodeList;
 
 //-------------------------------------------------------------------------
 
+class XMLData;
+
 /** Virtual base to handle different kinds of parent nodes
  */
-class XMLData;
 
 class XMLParentNode : public XMLChildNode
 {
@@ -140,7 +141,7 @@ protected:
               }
     XMLParentNode(): pChildList(NULL){
     }
-    /// Copyconstructor
+
     XMLParentNode( const XMLParentNode& );
 
     XMLParentNode& operator=(const XMLParentNode& obj);
@@ -178,7 +179,6 @@ typedef boost::unordered_map<OString, sal_Bool, OStringHash> TagMap;
 /** Holds information of a XML file, is root node of tree
  */
 
-
 class XMLFile : public XMLParentNode
 {
 public:
@@ -208,7 +208,7 @@ public:
     const std::vector<OString> getOrder(){ return order; }
 
 protected:
-    // writes a string as UTF8 with dos line ends to a given stream
+    /// writes a string as UTF8 with dos line ends to a given stream
     void        WriteString( ofstream &rStream, const OUString &sString );
 
     void        InsertL10NElement( XMLElement* pElement);
@@ -225,7 +225,6 @@ protected:
 };
 
 /// An Utility class for XML
-/// See RFC 3066 / #i8252# for ISO codes
 class XMLUtil{
 
 public:
@@ -237,7 +236,6 @@ public:
 };
 
 
-
 //-------------------------------------------------------------------------
 
 /** Hold information of an element node
@@ -258,7 +256,7 @@ private:
 protected:
     void Print(XMLNode *pCur, OUStringBuffer& buffer , bool rootelement);
 public:
-    /// create a element node
+    /// create an element node
     XMLElement(){}
     XMLElement(
         const OUString &rName,    // the element name
@@ -293,7 +291,7 @@ public:
 
     void ChangeLanguageTag( const OUString &rValue );
 
-    // Return a Unicode String representation of this object
+    /// Return a Unicode String representation of this object
     OUString ToOUString();
 
     void SetProject         ( OString const & prj        ){ project = prj;        }
@@ -417,10 +415,10 @@ public:
 /** struct for error information, used by class SimpleXMLParser
  */
 struct XMLError {
-    XML_Error eCode;    // the error code
-    std::size_t nLine; // error line number
-    std::size_t nColumn; // error column number
-    OUString sMessage;    // readable error message
+    XML_Error eCode;    ///< the error code
+    std::size_t nLine; ///< error line number
+    std::size_t nColumn; ///< error column number
+    OUString sMessage;    ///< readable error message
 };
 
 //-------------------------------------------------------------------------
@@ -428,7 +426,6 @@ struct XMLError {
 /** validating xml parser, creates a document tree with xml nodes
  */
 
-
 class SimpleXMLParser
 {
 private:
@@ -468,6 +465,6 @@ public:
     const XMLError &GetError() { return aErrorInformation; }
 };
 
-#endif
+#endif // BOOTSTRP_XMLPARSE_HXX
 
 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */
diff --git a/l10ntools/inc/xrmmerge.hxx b/l10ntools/inc/xrmmerge.hxx
index a2a8906a1b17..f5de9af9bc2e 100644
--- a/l10ntools/inc/xrmmerge.hxx
+++ b/l10ntools/inc/xrmmerge.hxx
@@ -17,14 +17,15 @@
  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  */
 
+#ifndef XRMMERGE_INCLUDED
+#define XRMMERGE_INCLUDED
+
 #include "sal/config.h"
 
 #include <fstream>
 
-//
-// XRMResParser
-//
 
+/// Parser for *.xrm and description.xml files
 class XRMResParser
 {
 private:
@@ -68,10 +69,8 @@ public:
     sal_Bool GetError() { return bError; }
 };
 
-//
-// XRMResExport
-//
 
+/// Export strings from *.xrm and description.xml files
 class XRMResExport : public XRMResParser
 {
 private:
@@ -101,10 +100,8 @@ public:
     virtual ~XRMResExport();
 };
 
-//
-// class XRMResMerge
-//
 
+/// Merge strings to *.xrm and description.xml files
 class XRMResMerge : public XRMResParser
 {
 private:
@@ -137,4 +134,6 @@ public:
     virtual ~XRMResMerge();
 };
 
+#endif // XRMMERGE_INCLUDED
+
 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */