sw: document SwRootFrame -> SwLinePortion encapsulation chain

Change-Id: I4c8b7ce0375c97b6947f201aa2389c00089b8f5a
Reviewed-on: https://gerrit.libreoffice.org/44751
Reviewed-by: Miklos Vajna <vmiklos@collabora.co.uk>
Tested-by: Jenkins <ci@libreoffice.org>

6 files changed, 12 insertions, 4 deletions

diff --git a/sw/source/core/inc/bodyfrm.hxx b/sw/source/core/inc/bodyfrm.hxx
index 1fa48fd66e12..658585d9856b 100644
--- a/sw/source/core/inc/bodyfrm.hxx
+++ b/sw/source/core/inc/bodyfrm.hxx
@@ -24,6 +24,8 @@
 
 class SwBorderAttrs;
 
+/// Container of body content (i.e. not header or footer). Typical parent is an
+/// SwPageFrame, typical lower is an SwTextFrame.
 class SwBodyFrame: public SwLayoutFrame
 {
 protected:
diff --git a/sw/source/core/inc/pagefrm.hxx b/sw/source/core/inc/pagefrm.hxx
index e6b4d92777d2..d49b5275893d 100644
--- a/sw/source/core/inc/pagefrm.hxx
+++ b/sw/source/core/inc/pagefrm.hxx
@@ -36,7 +36,8 @@ namespace vcl { class Font; }
 class SwSortedObjs;
 class SwAnchoredObject;
 
-/// A page of the document layout.
+/// A page of the document layout. Upper frame is expected to be an SwRootFrame
+/// instance. At least an SwBodyFrame lower is expected.
 class SwPageFrame: public SwFootnoteBossFrame
 {
     friend class SwFrame;
diff --git a/sw/source/core/inc/rootfrm.hxx b/sw/source/core/inc/rootfrm.hxx
index 73c020e8e9a8..1767a0814e0e 100644
--- a/sw/source/core/inc/rootfrm.hxx
+++ b/sw/source/core/inc/rootfrm.hxx
@@ -68,7 +68,8 @@ using SwCurrShells = std::set<CurrShell*>;
 class SwSectionFrame;
 using SwDestroyList = std::set<SwSectionFrame*>;
 
-/// The root element of a Writer document layout.
+/// The root element of a Writer document layout. Lower frames are expected to
+/// be SwPageFrame instances.
 class SwRootFrame: public SwLayoutFrame
 {
     // Needs to disable the Superfluous temporarily
diff --git a/sw/source/core/inc/txtfrm.hxx b/sw/source/core/inc/txtfrm.hxx
index dce33a89a882..19931c15d686 100644
--- a/sw/source/core/inc/txtfrm.hxx
+++ b/sw/source/core/inc/txtfrm.hxx
@@ -45,7 +45,8 @@ class SwScriptInfo;
 
 #define NON_PRINTING_CHARACTER_COLOR RGB_COLORDATA(0x26, 0x8b, 0xd2)
 
-/// Represents the visualization of a paragraph.
+/// Represents the visualization of a paragraph. Typical upper is an
+/// SwBodyFrame. The first text portion of the first line is az SwParaPortion.
 class SW_DLLPUBLIC SwTextFrame: public SwContentFrame
 {
     friend class SwTextIter;
diff --git a/sw/source/core/text/porlay.hxx b/sw/source/core/text/porlay.hxx
index 6aa245d053b4..c77f25b84981 100644
--- a/sw/source/core/text/porlay.hxx
+++ b/sw/source/core/text/porlay.hxx
@@ -73,7 +73,8 @@ public:
     void   SetRightOfst( const SwTwips nNew ) { nRightOfst = nNew; }
 };
 
-/// Collection of SwLinePortion instances, representing one line of text
+/// Collection of SwLinePortion instances, representing one line of text.
+/// Typically owned by an SwParaPortion.
 class SwLineLayout : public SwTextPortion
 {
 private:
@@ -226,6 +227,7 @@ public:
 };
 
 /// Collection of SwLineLayout instances, represents the paragraph text in Writer layout.
+/// Typically owned by an SwTextFrame.
 class SwParaPortion : public SwLineLayout
 {
     // Area that needs repainting
diff --git a/sw/source/core/text/porlin.hxx b/sw/source/core/text/porlin.hxx
index c95c052f1171..e048a36fe3e0 100644
--- a/sw/source/core/text/porlin.hxx
+++ b/sw/source/core/text/porlin.hxx
@@ -56,6 +56,7 @@ class SwPortionHandler;
 #define PORGRP_TOXREF   0x0008
 
 /// Base class for anything that can be part of a line in the Writer layout.
+/// Typically owned by SwLineLayout.
 class SwLinePortion: public SwPosSize
 {
 protected: