doxygen-ize comments in sw/source/core/draw

Change-Id: I04ef6f0992e6d00dd6519eb6e9bcddecbb97e8de

4 files changed, 92 insertions, 107 deletions

diff --git a/sw/source/core/draw/dcontact.cxx b/sw/source/core/draw/dcontact.cxx
index 896d01e3d145..941bf6c87c2d 100644
--- a/sw/source/core/draw/dcontact.cxx
+++ b/sw/source/core/draw/dcontact.cxx
@@ -67,7 +67,6 @@
 
 using namespace ::com::sun::star;
 
-
 TYPEINIT1( SwContact, SwClient )
 TYPEINIT1( SwFlyDrawContact, SwContact )
 TYPEINIT1( SwDrawContact, SwContact )
@@ -88,13 +87,12 @@ void setContextWritingMode( SdrObject* pObj, SwFrm* pAnchor )
     }
 }
 
-
-// The Get reverse way: seeks the format to the specified object.
-// If the object is a SwVirtFlyDrawObj then the format of this
-// will be acquired.
-// Otherwise it is just a simple drawing object. This has a
-// UserCall and is the client of the searched format.
-
+/** The Get reverse way: seeks the format to the specified object.
+ * If the object is a SwVirtFlyDrawObj then the format of this
+ * will be acquired.
+ * Otherwise it is just a simple drawing object. This has a
+ * UserCall and is the client of the searched format.
+*/
 SwFrmFmt *FindFrmFmt( SdrObject *pObj )
 {
     SwFrmFmt* pRetval = 0L;
@@ -151,9 +149,7 @@ SwRect GetBoundRectOfAnchoredObj( const SdrObject* pObj )
     return aRet;
 }
 
-/** Returns the UserCall if applicable from the group object
-    #i26791# - change return type
-*/
+/// Returns the UserCall if applicable from the group object
 SwContact* GetUserCall( const SdrObject* pObj )
 {
     SdrObject *pTmp;
@@ -486,9 +482,11 @@ void SwFlyDrawContact::Modify( const SfxPoolItem*, const SfxPoolItem * )
 {
 }
 
-// override method to control Writer fly frames,
-// which are linked, and to assure that all objects anchored at/inside the
-// Writer fly frame are also made visible.
+/**
+ * @note Overriding method to control Writer fly frames, which are linked, and
+ *       to assure that all objects anchored at/inside the Writer fly frame are
+ *       also made visible.
+ */
 void SwFlyDrawContact::MoveObjToVisibleLayer( SdrObject* _pDrawObj )
 {
     OSL_ENSURE( _pDrawObj->ISA(SwVirtFlyDrawObj),
@@ -525,9 +523,11 @@ void SwFlyDrawContact::MoveObjToVisibleLayer( SdrObject* _pDrawObj )
     SwContact::MoveObjToVisibleLayer( _pDrawObj );
 }
 
-// override method to control Writer fly frames,
-// which are linked, and to assure that all objects anchored at/inside the
-// Writer fly frame are also made invisible.
+/**
+ * @note Override method to control Writer fly frames, which are linked, and
+ *       to assure that all objects anchored at/inside the Writer fly frame are
+ *       also made invisible.
+ */
 void SwFlyDrawContact::MoveObjToInvisibleLayer( SdrObject* _pDrawObj )
 {
     OSL_ENSURE( _pDrawObj->ISA(SwVirtFlyDrawObj),
@@ -607,8 +607,8 @@ SwDrawContact::SwDrawContact( SwFrmFmt* pToRegisterIn, SdrObject* pObj ) :
                                 InsertObject( pObj, pObj->GetOrdNumDirect() );
     }
 
-    //Controls have to be always in the Control-Layer. This is also true for
-    //group objects, if they contain controls.
+    // Controls have to be always in the Control-Layer. This is also true for
+    // group objects, if they contain controls.
     if ( ::CheckControlLayer( pObj ) )
     {
         // set layer of object to corresponding invisible layer.
@@ -763,11 +763,12 @@ SdrObject* SwDrawContact::GetMaster()
            : 0L;
 }
 
-// overload <SwContact::SetMaster(..)> in order to
-// assert, if the 'master' drawing object is replaced.
-// replace of master object correctly handled, if
-// handled by method <SwDrawContact::ChangeMasterObject(..)>. Thus, assert
-// only, if a debug level is given.
+/**
+ * @note Overloading <SwContact::SetMaster(..)> in order to assert, if the
+ *       'master' drawing object is replaced. The latter is correctly handled,
+ *       if handled by method <SwDrawContact::ChangeMasterObject(..)>. Thus,
+ *       assert only, if a debug level is given.
+ */
 void SwDrawContact::SetMaster( SdrObject* _pNewMaster )
 {
     if ( _pNewMaster )
@@ -822,7 +823,7 @@ SwFrm* SwDrawContact::GetAnchorFrm( SdrObject* _pDrawObj )
     return pAnchorFrm;
 }
 
-// method to create a new 'virtual' drawing object.
+/// create a new 'virtual' drawing object.
 SwDrawVirtObj* SwDrawContact::CreateVirtObj()
 {
     // determine 'master'
@@ -837,9 +838,11 @@ SwDrawVirtObj* SwDrawContact::CreateVirtObj()
     return pNewDrawVirtObj;
 }
 
-// destroys a given 'virtual' drawing object.
-// side effect: 'virtual' drawing object is removed from data structure
-//              <maDrawVirtObjs>.
+/** destroys a given 'virtual' drawing object.
+ *
+ * side effect: 'virtual' drawing object is removed from data structure
+ *              <maDrawVirtObjs>.
+ */
 void SwDrawContact::DestroyVirtObj( SwDrawVirtObj* _pVirtObj )
 {
     if ( _pVirtObj )
@@ -849,8 +852,10 @@ void SwDrawContact::DestroyVirtObj( SwDrawVirtObj* _pVirtObj )
     }
 }
 
-// add a 'virtual' drawing object to drawing page.
-// Use an already created one, which isn't used, or create a new one.
+/** add a 'virtual' drawing object to drawing page.
+ *
+ * Use an already created one, which isn't used, or create a new one.
+ */
 SwDrawVirtObj* SwDrawContact::AddVirtObj()
 {
     SwDrawVirtObj* pAddedDrawVirtObj = 0L;
@@ -875,7 +880,7 @@ SwDrawVirtObj* SwDrawContact::AddVirtObj()
     return pAddedDrawVirtObj;
 }
 
-// remove 'virtual' drawing objects and destroy them.
+/// remove 'virtual' drawing objects and destroy them.
 void SwDrawContact::RemoveAllVirtObjs()
 {
     for ( std::list<SwDrawVirtObj*>::iterator aDrawVirtObjsIter = maDrawVirtObjs.begin();
@@ -925,7 +930,7 @@ bool SwDrawContact::VirtObjAnchoredAtFrmPred::operator() ( const SwDrawVirtObj*
     return ( pObjAnchorFrm == mpAnchorFrm );
 }
 
-// get drawing object ('master' or 'virtual') by frame.
+/// get drawing object ('master' or 'virtual') by frame.
 SdrObject* SwDrawContact::GetDrawObjectByAnchorFrm( const SwFrm& _rAnchorFrm )
 {
     SdrObject* pRetDrawObj = 0L;
@@ -1091,8 +1096,8 @@ void SwDrawContact::Changed( const SdrObject& rObj,
         pTmpRoot->EndAllAction();
 }
 
-// helper class for method <SwDrawContact::_Changed(..)> for handling nested
-// <SdrObjUserCall> events
+/// helper class for method <SwDrawContact::_Changed(..)> for handling nested
+/// <SdrObjUserCall> events
 class NestedUserCallHdl
 {
     private:
@@ -1635,7 +1640,7 @@ void SwDrawContact::DisconnectFromLayout( bool _bMoveMasterToInvisibleLayer )
     mbDisconnectInProgress = false;
 }
 
-// method to remove 'master' drawing object from drawing page.
+/// method to remove 'master' drawing object from drawing page.
 void SwDrawContact::RemoveMasterFromDrawPage()
 {
     if ( GetMaster() )
@@ -1889,7 +1894,7 @@ void SwDrawContact::ConnectToLayout( const SwFmtAnchor* pAnch )
     }
 }
 
-// insert 'master' drawing object into drawing page
+/// insert 'master' drawing object into drawing page
 void SwDrawContact::InsertMasterIntoDrawPage()
 {
     if ( !GetMaster()->IsInserted() )
@@ -1966,7 +1971,7 @@ void SwDrawContact::ChangeMasterObject( SdrObject *pNewMaster )
     _InvalidateObjs();
 }
 
-// get data collection of anchored objects, handled by with contact
+/// get data collection of anchored objects, handled by with contact
 void SwDrawContact::GetAnchoredObjs( std::list<SwAnchoredObject*>& _roAnchoredObjs ) const
 {
     _roAnchoredObjs.push_back( const_cast<SwAnchoredDrawObject*>(&maAnchoredDrawObj) );
@@ -1991,11 +1996,14 @@ namespace sdr
         class VOCOfDrawVirtObj : public ViewObjectContactOfSdrObj
         {
         protected:
-            // This method is responsible for creating the graphical visualisation data which is
-            // stored/cached in the local primitive. Default gets view-independent Primitive
-            // from the ViewContact using ViewContact::getViewIndependentPrimitive2DSequence(), takes care of
-            // visibility, handles glue and ghosted.
-            // This method will not handle included hierarchies and not check geometric visibility.
+            /**
+             * This method is responsible for creating the graphical visualisation data which is
+             * stored/cached in the local primitive. Default gets view-independent Primitive from
+             * the ViewContact using ViewContact::getViewIndependentPrimitive2DSequence(), takes
+             * care of visibility, handles glue and ghosted.
+             *
+             * This method will not handle included hierarchies and not check geometric visibility.
+             */
             virtual drawinglayer::primitive2d::Primitive2DSequence createPrimitive2DSequence(const DisplayInfo& rDisplayInfo) const;
 
         public:
@@ -2010,20 +2018,22 @@ namespace sdr
         class VCOfDrawVirtObj : public ViewContactOfVirtObj
         {
         protected:
-            // Create a Object-Specific ViewObjectContact, set ViewContact and
-            // ObjectContact. Always needs to return something. Default is to create
-            // a standard ViewObjectContact containing the given ObjectContact and *this
+            /** Create a Object-Specific ViewObjectContact, set ViewContact and ObjectContact.
+             *
+             * Always needs to return something. Default is to create a standard ViewObjectContact
+             * containing the given ObjectContact and *this.
+             */
             virtual ViewObjectContact& CreateObjectSpecificViewObjectContact(ObjectContact& rObjectContact);
 
         public:
-            // basic constructor, used from SdrObject.
+            /// basic constructor, used from SdrObject.
             VCOfDrawVirtObj(SwDrawVirtObj& rObj)
             :   ViewContactOfVirtObj(rObj)
             {
             }
             virtual ~VCOfDrawVirtObj();
 
-            // access to SwDrawVirtObj
+            /// access to SwDrawVirtObj
             SwDrawVirtObj& GetSwDrawVirtObj() const
             {
                 return (SwDrawVirtObj&)mrObject;
@@ -2036,7 +2046,7 @@ namespace sdr
 {
     namespace contact
     {
-        // recursively collect primitive data from given VOC with given offset
+        /// recursively collect primitive data from given VOC with given offset
         void impAddPrimitivesFromGroup(const ViewObjectContact& rVOC, const basegfx::B2DHomMatrix& rOffsetMatrix, const DisplayInfo& rDisplayInfo, drawinglayer::primitive2d::Primitive2DSequence& rxTarget)
         {
             const sal_uInt32 nSubHierarchyCount(rVOC.GetViewContact().GetObjectCount());
@@ -2263,7 +2273,7 @@ void SwDrawVirtObj::RemoveFromDrawingPage()
     }
 }
 
-// is 'virtual' drawing object connected to writer layout and to drawing layer.
+/// Is 'virtual' drawing object connected to writer layout and to drawing layer?
 bool SwDrawVirtObj::IsConnected() const
 {
     bool bRetVal = GetAnchorFrm() &&
diff --git a/sw/source/core/draw/dflyobj.cxx b/sw/source/core/draw/dflyobj.cxx
index eb996809be97..80d60d4c3976 100644
--- a/sw/source/core/draw/dflyobj.cxx
+++ b/sw/source/core/draw/dflyobj.cxx
@@ -23,7 +23,6 @@
 #include <editeng/opaqitem.hxx>
 #include <svx/svdpage.hxx>
 
-
 #include <fmtclds.hxx>
 #include <fmtornt.hxx>
 #include <fmtfsize.hxx>
@@ -70,19 +69,25 @@ namespace sdr
 {
     namespace contact
     {
-        // #i95264# currently needed since createViewIndependentPrimitive2DSequence()
-        // is called when RecalcBoundRect() is used. There should currently no VOCs being
-        // constructed since it gets not visualized (instead the corresponding SwVirtFlyDrawObj's
-        // referencing this one are visualized).
+        /**
+         * @see #i95264#
+         *
+         * currently needed since createViewIndependentPrimitive2DSequence() is called when
+         * RecalcBoundRect() is used. There should currently no VOCs being constructed since it
+         * gets not visualized (instead the corresponding SwVirtFlyDrawObj's referencing this one
+         * are visualized).
+         */
         class VCOfSwFlyDrawObj : public ViewContactOfSdrObj
         {
         protected:
-            // This method is responsible for creating the graphical visualisation data
-            // ONLY based on model data
+            /** This method is responsible for creating the graphical visualisation data
+             *
+             * @note ONLY based on model data
+             */
             virtual drawinglayer::primitive2d::Primitive2DSequence createViewIndependentPrimitive2DSequence() const;
 
         public:
-            // basic constructor, used from SdrObject.
+            /// basic constructor, used from SdrObject.
             VCOfSwFlyDrawObj(SwFlyDrawObj& rObj)
             :   ViewContactOfSdrObj(rObj)
             {
@@ -131,16 +136,14 @@ sal_uInt32 SwFlyDrawObj::GetObjInventor() const
     return SWGInventor;
 }
 
-
 sal_uInt16 SwFlyDrawObj::GetObjIdentifier() const
 {
     return SwFlyDrawObjIdentifier;
 }
 
-
 // SwVirtFlyDrawObj::CToren, Dtor
 
-// AW: Need own primitive to get the FlyFrame paint working
+// TODO: Need own primitive to get the FlyFrame paint working
 
 namespace drawinglayer
 {
@@ -153,7 +156,7 @@ namespace drawinglayer
             const basegfx::B2DRange                 maOuterRange;
 
         protected:
-            // method which is to be used to implement the local decomposition of a 2D primitive
+            /// method which is to be used to implement the local decomposition of a 2D primitive
             virtual Primitive2DSequence create2DDecomposition(const geometry::ViewInformation2D& rViewInformation) const;
 
         public:
@@ -179,7 +182,7 @@ namespace drawinglayer
             const SwVirtFlyDrawObj& getSwVirtFlyDrawObj() const { return mrSwVirtFlyDrawObj; }
             const basegfx::B2DRange& getOuterRange() const { return maOuterRange; }
 
-            // provide unique ID
+            /// provide unique ID
             DeclPrimitrive2DIDBlock()
         };
     } // end of namespace primitive2d
@@ -261,19 +264,21 @@ namespace sdr
         class VCOfSwVirtFlyDrawObj : public ViewContactOfVirtObj
         {
         protected:
-            // This method is responsible for creating the graphical visualisation data
-            // ONLY based on model data
+            /** This method is responsible for creating the graphical visualisation data
+             *
+             * @note ONLY based on model data
+             */
             virtual drawinglayer::primitive2d::Primitive2DSequence createViewIndependentPrimitive2DSequence() const;
 
         public:
-            // basic constructor, used from SdrObject.
+            /// basic constructor, used from SdrObject.
             VCOfSwVirtFlyDrawObj(SwVirtFlyDrawObj& rObj)
             :   ViewContactOfVirtObj(rObj)
             {
             }
             virtual ~VCOfSwVirtFlyDrawObj();
 
-            // access to SwVirtFlyDrawObj
+            /// access to SwVirtFlyDrawObj
             SwVirtFlyDrawObj& GetSwVirtFlyDrawObj() const
             {
                 return (SwVirtFlyDrawObj&)mrObject;
@@ -317,7 +322,6 @@ namespace sdr
     } // end of namespace contact
 } // end of namespace sdr
 
-
 basegfx::B2DRange SwVirtFlyDrawObj::getOuterBound() const
 {
     basegfx::B2DRange aOuterRange;
@@ -529,26 +533,22 @@ const Rectangle& SwVirtFlyDrawObj::GetLastBoundRect() const
     return GetCurrentBoundRect();
 }
 
-
 void SwVirtFlyDrawObj::RecalcBoundRect()
 {
     SetRect();
 }
 
-
 void SwVirtFlyDrawObj::RecalcSnapRect()
 {
     SetRect();
 }
 
-
 const Rectangle& SwVirtFlyDrawObj::GetSnapRect()  const
 {
     SetRect();
     return aOutRect;
 }
 
-
 void SwVirtFlyDrawObj::SetSnapRect(const Rectangle& )
 {
     Rectangle aTmp( GetLastBoundRect() );
@@ -559,20 +559,17 @@ void SwVirtFlyDrawObj::SetSnapRect(const Rectangle& )
         pUserCall->Changed(*this, SDRUSERCALL_RESIZE, aTmp);
 }
 
-
 void SwVirtFlyDrawObj::NbcSetSnapRect(const Rectangle& )
 {
     SetRect();
 }
 
-
 const Rectangle& SwVirtFlyDrawObj::GetLogicRect() const
 {
     SetRect();
     return aOutRect;
 }
 
-
 void SwVirtFlyDrawObj::SetLogicRect(const Rectangle& )
 {
     Rectangle aTmp( GetLastBoundRect() );
@@ -583,13 +580,11 @@ void SwVirtFlyDrawObj::SetLogicRect(const Rectangle& )
         pUserCall->Changed(*this, SDRUSERCALL_RESIZE, aTmp);
 }
 
-
 void SwVirtFlyDrawObj::NbcSetLogicRect(const Rectangle& )
 {
     SetRect();
 }
 
-
 ::basegfx::B2DPolyPolygon SwVirtFlyDrawObj::TakeXorPoly() const
 {
     const Rectangle aSourceRectangle(GetFlyFrm()->Frm().SVRect());
@@ -748,7 +743,6 @@ void SwVirtFlyDrawObj::NbcMove(const Size& rSiz)
         pFmt->SetFmtAttr( aSet );
 }
 
-
 void SwVirtFlyDrawObj::NbcResize(const Point& rRef,
             const Fraction& xFact, const Fraction& yFact)
 {
@@ -856,7 +850,6 @@ void SwVirtFlyDrawObj::NbcResize(const Point& rRef,
     }
 }
 
-
 void SwVirtFlyDrawObj::Move(const Size& rSiz)
 {
     NbcMove( rSiz );
@@ -864,7 +857,6 @@ void SwVirtFlyDrawObj::Move(const Size& rSiz)
     GetFmt()->GetDoc()->GetIDocumentUndoRedo().DoDrawUndo(false);
 }
 
-
 void SwVirtFlyDrawObj::Resize(const Point& rRef,
                     const Fraction& xFact, const Fraction& yFact, bool /*bUnsetRelative*/)
 {
@@ -880,14 +872,12 @@ Pointer  SwVirtFlyDrawObj::GetMacroPointer(
     return Pointer( POINTER_REFHAND );
 }
 
-
 bool SwVirtFlyDrawObj::HasMacro() const
 {
     const SwFmtURL &rURL = pFlyFrm->GetFmt()->GetURL();
     return rURL.GetMap() || rURL.GetURL().Len();
 }
 
-
 SdrObject* SwVirtFlyDrawObj::CheckMacroHit( const SdrObjMacroHitRec& rRec ) const
 {
     const SwFmtURL &rURL = pFlyFrm->GetFmt()->GetURL();
diff --git a/sw/source/core/draw/drawdoc.cxx b/sw/source/core/draw/drawdoc.cxx
index 0ebf8e9b8c0d..16ca510e9d15 100644
--- a/sw/source/core/draw/drawdoc.cxx
+++ b/sw/source/core/draw/drawdoc.cxx
@@ -17,7 +17,6 @@
  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  */
 
-
 #include <svx/svxids.hrc>
 #include <tools/stream.hxx>
 #include <unotools/pathoptions.hxx>
@@ -125,11 +124,13 @@ SwDrawDocument::~SwDrawDocument()
     ClearModel(sal_True);
 }
 
-// This method creates a new page (SdPage) and thereupon returns a pointer
-// to it back. The drawing engine is using this method while loading for
-// the creating of pages (whose type it not even know, because they are
-// inherited from SdrPage).
-
+/** Create a new page (SdPage) and return a pointer to it back.
+ *
+ * The drawing engine is using this method while loading for the creating of
+ * pages (whose type it not even know, because they are inherited from SdrPage).
+ *
+ * @return Pointer to the new page.
+ */
 SdrPage* SwDrawDocument::AllocPage(bool bMasterPage)
 {
     SwDPage* pPage = new SwDPage(*this, 0 != bMasterPage);
@@ -150,7 +151,6 @@ SdrLayerID SwDrawDocument::GetControlExportLayerId( const SdrObject & ) const
 
 uno::Reference< uno::XInterface > SwDrawDocument::createUnoModel()
 {
-
     uno::Reference< uno::XInterface > xModel;
 
     try
@@ -168,5 +168,4 @@ uno::Reference< uno::XInterface > SwDrawDocument::createUnoModel()
     return xModel;
 }
 
-
 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */
diff --git a/sw/source/core/draw/dview.cxx b/sw/source/core/draw/dview.cxx
index e76be4e910f3..7c31b2bc9f03 100644
--- a/sw/source/core/draw/dview.cxx
+++ b/sw/source/core/draw/dview.cxx
@@ -202,9 +202,7 @@ SdrObject* SwDrawView::CheckSingleSdrObjectHit(const Point& rPnt, sal_uInt16 nTo
     return pRetval;
 }
 
-// SwDrawView::AddCustomHdl()
-// Gets called every time the handles need to be build
-
+/// Gets called every time the handles need to be build
 void SwDrawView::AddCustomHdl()
 {
     const SdrMarkList &rMrkList = GetMarkedObjectList();
@@ -317,11 +315,7 @@ SdrObject* SwDrawView::GetMaxToBtmObj(SdrObject* pObj) const
     return 0;
 }
 
-// SwDrawView::ObjOrderChanged()
-
-// determine maximal order number for a 'child' object of given 'parent' object
-// @author OD
-
+/// determine maximal order number for a 'child' object of given 'parent' object
 sal_uInt32 SwDrawView::_GetMaxChildOrdNum( const SwFlyFrm& _rParentObj,
                                            const SdrObject* _pExclChildObj ) const
 {
@@ -353,11 +347,7 @@ sal_uInt32 SwDrawView::_GetMaxChildOrdNum( const SwFlyFrm& _rParentObj,
     return nMaxChildOrdNum;
 }
 
-/** method to move 'repeated' objects of the given moved object to the
- *  according level
- *
- *  @author OD
- */
+/// method to move 'repeated' objects of the given moved object to the according level
 void SwDrawView::_MoveRepeatedObjs( const SwAnchoredObject& _rMovedAnchoredObj,
                                     const std::vector<SdrObject*>& _rMovedChildObjs ) const
 {
@@ -908,11 +898,7 @@ void SwDrawView::CheckPossibilities()
     bResizeProtect  |= bProtect | bSzProtect;
 }
 
-/** replace marked <SwDrawVirtObj>-objects by its reference object for delete
- *  marked objects.
- *
- *  @author OD
-*/
+/// replace marked <SwDrawVirtObj>-objects by its reference object for delete marked objects.
 void SwDrawView::ReplaceMarkedDrawVirtObjs( SdrMarkView& _rMarkView )
 {
     SdrPageView* pDrawPageView = _rMarkView.GetSdrPageView();