CharBrd 10: Some documentation

Change-Id: I4c6c2cd4acf8ae4a759a662f92066ad63df74b3c

dictionaries @ a32a341e

-Subproject commit b07ae33b0d25e33bf890fab8fbcd3317506bbeae
+Subproject commit a32a341efdbb9e53a7b832262a41f6fb6454bedf

sw/qa/extras/inc/swmodeltestbase.hxx

@@ -359,6 +359,16 @@ protected:
     sal_uInt32 m_nStartTime;
 };
 
+/**
+ * Test whether the expected and actual borderline parameters are equal
+ * and assert if not.
+ *
+ * @param[in]   rExpected    expected borderline object
+ * @param[in]   rActual      actual borderline object
+ * @param[in]   rSourceLine  line from where the assertion is called
+ * Note: This method is the implementatition of CPPUNIT_ASSERT_BORDER_EQUAL, so
+ *       use that macro instead.
+**/
 inline void assertBorderEqual(
     const table::BorderLine2& rExpected, const table::BorderLine2& rActual,
     const CppUnit::SourceLine& rSourceLine )

sw/source/core/inc/frmtool.hxx

@@ -65,7 +65,15 @@ void SwAlignRect( SwRect &rRect, const ViewShell *pSh );
 // Created declaration here to avoid <extern> declarations
 void SwAlignGrfRect( SwRect *pGrfRect, const OutputDevice &rOut );
 
-// Paint character border using frame painting code
+/**
+ * Paint border around a run of characters using frame painting code.
+ *
+ * @param[in]   rFont            font object of actual text, which specify the border
+ * @param[in]   rPaintArea       rectangle area in which line portion takes place
+ * @param[in]   bVerticalLayout  corresponding text frame verticality
+ * @param[in]   bJoinWithPrev    leave border with which actual border joins to the previous portion
+ * @param[in]   bJoinWithNext    leave border with which actual border joins to the next portion
+**/
 void PaintCharacterBorder(
     const SwFont& rFont, const SwRect& rPaintArea, const bool bVerticalLayout,
     const bool bJoinWithPrev, const bool bJoinWithNext );

sw/source/core/inc/swfont.hxx

@@ -370,7 +370,6 @@ public:
     inline void Invalidate()
         { bFntChg = bOrgChg = sal_True; }
 
-    // set/get borders
     void SetTopBorder( const editeng::SvxBorderLine* pTopBorder );
     void SetBottomBorder( const editeng::SvxBorderLine* pBottomBorder );
     void SetRightBorder( const editeng::SvxBorderLine* pRightBorder );
@@ -381,7 +380,7 @@ public:
     const boost::optional<editeng::SvxBorderLine>& GetRightBorder() const { return m_aRightBorder; }
     const boost::optional<editeng::SvxBorderLine>& GetLeftBorder() const { return m_aLeftBorder; }
 
-    // Get borders which are at absolute positions
+    // Get absolute border correspond to the layout verticality and orientation.
     const boost::optional<editeng::SvxBorderLine>& GetAbsTopBorder( const bool bVertLayout ) const;
     const boost::optional<editeng::SvxBorderLine>& GetAbsBottomBorder( const bool bVertLayout ) const;
     const boost::optional<editeng::SvxBorderLine>& GetAbsRightBorder( const bool bVertLayout ) const;
@@ -397,22 +396,22 @@ public:
     sal_uInt16 GetRightBorderDist() const { return m_nRightBorderDist; }
     sal_uInt16 GetLeftBorderDist() const { return m_nLeftBorderDist; }
 
-    // Return with the border width plus spacing
+    // Return with the whole space which border holed (border width, spacing and shadow width)
     sal_uInt16 GetTopBorderSpace() const;
     sal_uInt16 GetBottomBorderSpace() const;
     sal_uInt16 GetRightBorderSpace() const;
     sal_uInt16 GetLeftBorderSpace() const;
 
+    /// Check whether font has any border on any side
     bool HasBorder() const;
 
-    // Shadow attributes
     void SetShadowColor( const Color& rColor );
     void SetShadowWidth( const sal_uInt16 nWidth );
     void SetShadowLocation( const SvxShadowLocation aLocation );
 
-    const Color& GetShadowColor() const { return m_aShadowColor; }
-    sal_uInt16 GetShadowWidth() const { return m_nShadowWidth; }
-    SvxShadowLocation GetShadowLocation() const { return m_aShadowLocation; }
+    const Color&        GetShadowColor() const { return m_aShadowColor; }
+    sal_uInt16          GetShadowWidth() const { return m_nShadowWidth; }
+    SvxShadowLocation   GetShadowLocation() const { return m_aShadowLocation; }
 
     /**
      * Get the absolute shadow location dependant from orientation.

sw/source/core/text/inftxt.hxx

@@ -443,6 +443,11 @@ public:
     void DrawViewOpt( const SwLinePortion &rPor, const MSHORT nWhich ) const;
     void DrawBackBrush( const SwLinePortion &rPor ) const;
 
+    /**
+     * Draw character border around a line portion.
+     *
+     * @param[in]   rPor    line portion around which border have to be drawn.
+    **/
     void DrawBorder( const SwLinePortion &rPor ) const;
 
     void DrawCheckBox( const SwFieldFormPortion &rPor, bool checked) const;

sw/source/ui/inc/chrdlgmodes.hxx

@@ -10,7 +10,7 @@
 #ifndef SW_CHAR_DLG_MODES_HXX
 #define SW_CHAR_DLG_MODES_HXX
 
-//DialogModes:
+// DialogModes for SwCharDlg
 #define DLG_CHAR_STD    0
 #define DLG_CHAR_DRAW   1
 #define DLG_CHAR_ENV    2

sw/source/ui/inc/uitool.hxx

@@ -39,19 +39,29 @@ class SfxViewFrame;
 // switch a metric
 SW_DLLPUBLIC void SetMetric(MetricFormatter& rCtrl, FieldUnit eUnit);
 
-// fill BoxInfoAttribut
+// fill BoxInfo attribute
 SW_DLLPUBLIC void PrepareBoxInfo(SfxItemSet& rSet, const SwWrtShell& rSh);
 
 // Modes for attribute conversion
 #define CONV_ATTR_STD    1  // Standard character dialog
 #define CONV_ATTR_ENV    2  // Character dialog opened from envelope dialog
 
-// Convert character specific attributes to general ones used by tab pages
-SW_DLLPUBLIC void ConvertAttrCharToGen(SfxItemSet& rSet, sal_uInt8 nMode);
-
-// Convert general attributes to the corresponding character attributes
-// This method is used after executed a character dialog
-SW_DLLPUBLIC void ConvertAttrGenToChar(SfxItemSet& rSet, sal_uInt8 nMode);
+/**
+ * Convert character specific attributes to general ones used by tab pages.
+ *
+ * @param[in|out]   rSet    the set in which character attributes are stored
+ * @param[in]       nMode   specify the dialog which will be called after conversion
+**/
+SW_DLLPUBLIC void ConvertAttrCharToGen(SfxItemSet& rSet, const sal_uInt8 nMode);
+
+/**
+ * Convert general attributes to the corresponding character attributes.
+ * This method is used after executed a character dialog.
+ *
+ * @param[in|out]   rSet    the set in which character attributes are stored
+ * @param[in]       nMode   specify the dialog which was called before
+**/
+SW_DLLPUBLIC void ConvertAttrGenToChar(SfxItemSet& rSet, const sal_uInt8 nMode);
 
 // SfxItemSets <-> PageDesc
 void ItemSetToPageDesc( const SfxItemSet& rSet, SwPageDesc& rPageDesc );

sw/source/ui/utlui/uitool.cxx

@@ -119,7 +119,7 @@ void PrepareBoxInfo(SfxItemSet& rSet, const SwWrtShell& rSh)
     rSet.Put(aBoxInfo);
 }
 
-void ConvertAttrCharToGen(SfxItemSet& rSet, sal_uInt8 nMode)
+void ConvertAttrCharToGen(SfxItemSet& rSet, const sal_uInt8 nMode)
 {
     // Background
     {
@@ -159,7 +159,7 @@ void ConvertAttrCharToGen(SfxItemSet& rSet, sal_uInt8 nMode)
     }
 }
 
-void ConvertAttrGenToChar(SfxItemSet& rSet, sal_uInt8 nMode)
+void ConvertAttrGenToChar(SfxItemSet& rSet, const sal_uInt8 nMode)
 {
     // Background
     {

xmloff/source/text/txtexppr.cxx

@@ -336,6 +336,11 @@ lcl_checkMultiProperty(XMLPropertyState *const pState,
     }
 }
 
+/**
+ * Filter context of paragraph and character borders.
+ * Compress border attriubtes. If one of groupable attributes (border type, border width, padding)
+ * is equal for all four side then just one general attribute will be exported.
+**/
 static void lcl_FilterBorders(
     XMLPropertyState* pAllBorderWidthState, XMLPropertyState* pLeftBorderWidthState,
     XMLPropertyState* pRightBorderWidthState, XMLPropertyState* pTopBorderWidthState,

xmloff/source/text/txtimppr.cxx

@@ -268,6 +268,12 @@ isNotDefaultRelSize(const XMLPropertyState* pRelState, const UniReference<XMLPro
     return true;
 }
 
+/**
+ * Separate compressed border attributes.
+ * During export, border attributes are compressed if there are equal to all four side.
+ * Since Writer hasn't the same compressed attributes, but has distinct ones for all
+ * four side, we have to duplicate the compressed attribute during import.
+**/
 static void lcl_SeparateBorder(
     sal_uInt16 nIndex, XMLPropertyState* pAllBorderDistance,
     XMLPropertyState* pBorderDistances[4], XMLPropertyState* pNewBorderDistances[4],