diff --git a/Prima/Calendar.pm b/Prima/Calendar.pm
index ce63c56f4..4e1cd8705 100644
--- a/Prima/Calendar.pm
+++ b/Prima/Calendar.pm
@@ -542,10 +542,10 @@ Prima::Calendar - standard calendar widget
 
 =head1 DESCRIPTION
 
-Provides interactive selection of date between 1900 and 2099 years.
-The main property, L<date>, is a three-integer array, day, month, and year,
+Provides interactive selection for dates between the years 1900 and 2099.
+The main property, L<date>, is a three-integer array of day, month, and year,
 in the format of perl localtime ( see L<perlfunc/localtime> ) -
-day can be in range from 1 to 31,month from 0 to 11, year from 0 to 199.
+day's range is between 1 and 31, month's 0 to 11, year's from 0 to 199.
 
 =head1 API
 
@@ -565,30 +565,30 @@ Called when the L<date> property is changed.
 
 =item date DAY, MONTH, YEAR
 
-Accepts three integers in format of C<localtime>.
+Accepts three integers in the format of C<localtime>.
 DAY can be from 1 to 31, MONTH from 0 to 11, YEAR from 0 to 199.
 
 Default value: today's date.
 
 =item day INTEGER
 
-Selects the day in month.
+Selects the day in the month.
 
 =item firstDayOfWeek INTEGER
 
-Selects the first day of week, an integer between 0 and 6,
-where 0 is Sunday is the first day, 1 is Monday etc.
+Selects the first day of the week, an integer between 0 and 6,
+where 0 is Sunday as the first day, 1 is Monday, etc.
 
 Default value: 0
 
 =item month
 
-Selects the month.
+Selects the month
 
 =item useLocale BOOLEAN
 
 If 1, the locale-specific names of months and days of week are used.
-These are read by calling C<POSIX::strftime>. If invocation of POSIX module
+These are read by calling C<POSIX::strftime>. If an invocation of the POSIX module
 fails, the property is automatically assigned to 0.
 
 If 0, the English names of months and days of week are used.
@@ -609,34 +609,34 @@ Selects the year.
 
 =item can_use_locale
 
-Returns boolean value, whether the locale information can be retrieved
-by calling C<strftime>.
+Returns a boolean value, whether the locale information can be retrieved
+by calling C<strftime> or not.
 
 =item month2str MONTH
 
-Returns MONTH name according to L<useLocale> value.
+Returns the MONTH name according to the L<useLocale> value.
 
 =item make_months
 
-Returns array of 12 month names according to L<useLocale> value.
+Returns an array of the 12 month names according to the L<useLocale> value.
 
 =item day_of_week DAY, MONTH, YEAR, [ USE_FIRST_DAY_OF_WEEK = 1 ]
 
-Returns integer value, from 0 to 6, of the day of week on
-DAY, MONTH, YEAR date. If boolean USE_FIRST_DAY_OF_WEEK is set,
-the value of C<firstDayOfWeek> property is taken into the account,
-so 0 is a Sunday shifted forward by C<firstDayOfWeek> days.
+Returns an integer value between 0 and 6, the day of week on DAY, MONTH, YEAR
+date. If boolean USE_FIRST_DAY_OF_WEEK is set, the value of the
+C<firstDayOfWeek> property is taken into account, so f ex the result of 0 means
+that this is a Sunday shifted forward by C<firstDayOfWeek> days.
 
-The switch from Julian to Gregorian calendar is ignored.
+The switch from the Julian to the Gregorian calendar is ignored.
 
 =item date_as_string [ DAY, MONTH, YEAR ]
 
 Returns string representation of date on DAY, MONTH, YEAR according
-to L<useLocale> property value.
+to the L<useLocale> property value.
 
 =item date_from_time SEC, MIN, HOUR, M_DAY, MONTH, YEAR, ...
 
-Copies L<date> from C<localtime> or C<gmtime> result. This helper method
+Copies L<date> from C<localtime> or C<gmtime> results. This helper method
 allows the following syntax:
 
 	$calendar-> date_from_time( localtime( time));
diff --git a/Prima/Classes.pm b/Prima/Classes.pm
index 0af1c2589..227fda475 100644
--- a/Prima/Classes.pm
+++ b/Prima/Classes.pm
@@ -2653,8 +2653,8 @@ Prima::Classes - binder module for the built-in classes.
 
 =head1 DESCRIPTION
 
-C<Prima::Classes> and L<Prima::Const> is a minimal set of perl modules needed for
-the toolkit. Since the module provides bindings for the core classes, it is required
+C<Prima::Classes> and L<Prima::Const> form a minimal set of perl modules needed for
+the toolkit to run. Since the module provides bindings for the core classes, it is required
 to be included in every Prima-related module and program.
 
 =head1 AUTHOR
diff --git a/Prima/ComboBox.pm b/Prima/ComboBox.pm
index e68afc38f..1f428651e 100644
--- a/Prima/ComboBox.pm
+++ b/Prima/ComboBox.pm
@@ -767,22 +767,22 @@ Prima::ComboBox - standard combo box widget
 
 =head1 DESCRIPTION
 
-Provides a combo box widget which consists of an input line, list box of possible
-selections and eventual drop-down button. The combo box can be either in form
-with a drop-down selection list, that is shown by the command of the user,
-or in form when the selection list is always visible.
-
-The combo box is a grouping widget, and contains neither painting nor user-input
-code. All such functionality is delegated into the children widgets: input line, list
-box and button. C<Prima::ComboBox> exports a fixed list of methods and properties from
-namespaces of L<Prima::InputLine> and L<Prima::ListBox>. Since, however, it is
-possible to tweak the C<Prima::ComboBox> ( using its L<editClass> and L<listClass>
-create-only properties ) so the input line and list box would be other classes,
-it is not necessarily that all default functionality would work.
-The list of exported names is stored in package variables %listProps, %editProps
-and %listDynas. These also described in L<Exported names> section.
-
-The module defines C<cs::> package for the constants used by L<style> property.
+Provides a combo box widget that consists of an input line, a list box of
+possible selections, and an eventual drop-down button. The combo box can be
+either in the form of a drop-down list that can be shown and hidden or in a
+form where the selection list is always visible.
+
+The combo box is a grouping widget and contains neither painting nor
+user input code by itself. All such functionality is delegated to the children
+widgets: input line, list box, and drop button. C<Prima::ComboBox> exports a
+fixed list of methods and properties from the namespaces of L<Prima::InputLine> and
+L<Prima::ListBox>. It is possible to tweak the C<Prima::ComboBox> ( using its
+L<editClass> and L<listClass> create-only properties ) so the input line and
+list box widgets can be instantiated from other classes.  The list of exported
+names is stored in package variables %listProps, %editProps, and %listDynas.
+These are also described in the L<Exported names> section.
+
+The module defines the C<cs::> package for the constants used by the L<style> property.
 
 =head1 API
 
@@ -793,13 +793,13 @@ The module defines C<cs::> package for the constants used by L<style> property.
 =item autoHeight BOOLEAN
 
 If 1, adjusts the height of the widget automatically when its font changes.
-Only when style is not C<cs::Simple>.
+Only for styles not equal to C<cs::Simple>.
 
 Default value: 1
 
 =item buttonClass STRING
 
-Assigns a drop-down button class.
+Assigns the drop-down button class.
 
 Create-only property.
 
@@ -807,13 +807,13 @@ Default value: C<Prima::Widget>
 
 =item buttonDelegations ARRAY
 
-Assigns a drop-down button list of delegated notifications.
+Assigns the list of delegated notifications to the drop-down button.
 
 Create-only property.
 
 =item buttonProfile HASH
 
-Assigns hash of properties, passed to the drop-down button during the creation.
+Assigns a hash of properties passed to the drop-down button during the creation.
 
 Create-only property.
 
@@ -826,7 +826,7 @@ Default value: 0
 
 =item editClass STRING
 
-Assigns an input line class.
+Assigns the input line class.
 
 Create-only property.
 
@@ -834,27 +834,27 @@ Default value: C<Prima::InputLine>
 
 =item editProfile HASH
 
-Assigns hash of properties, passed to the input line during the creation.
+Assigns a hash of properties passed to the input line during the creation.
 
 Create-only property.
 
 =item editDelegations ARRAY
 
-Assigns an input line list of delegated notifications.
+Assigns the list of delegated notifications to the input line.
 
 Create-only property.
 
 =item editHeight INTEGER
 
-Selects height of an input line.
+Selects the height of the input line.
 
 =item items ARRAY
 
-Mapped onto the list widget's C<items> property. See L<Prima::Lists> for details.
+Proxy of the list widget's C<items> property. See L<Prima::Lists> for details.
 
 =item listClass STRING
 
-Assigns a listbox class.
+Assigns the list box class.
 
 Create-only property.
 
@@ -862,63 +862,63 @@ Default value: C<Prima::ListBox>
 
 =item listHeight INTEGER
 
-Selects height of the listbox widget.
+Selects the height of the list box widget.
 
 Default value: 100
 
 =item listVisible BOOLEAN
 
-Sets whether the listbox is visible or not. Not writable
-when L<style> is C<cs::Simple>.
+Sets whether the list box is visible or not. Not writable
+when the C<style> is C<cs::Simple>.
 
 =item listProfile HASH
 
-Assigns hash of properties, passed to the listbox during the creation.
+Assigns a hash of properties passed to the list box during the creation.
 
 Create-only property.
 
 =item listDelegations ARRAY
 
-Assigns a selection listbox list of delegated notifications.
+Assigns the list of delegated notifications to the list box.
 
 Create-only property.
 
 =item literal BOOLEAN
 
-Selects whether the combo box user input routine assume that
-the listbox contains literal strings, that can be fetched via
-C<get_item_text> ( see L<Prima::Lists> ). As an example when
-this property is set to 0 is C<Prima::ColorComboBox> from L<Prima::ComboBox> package.
+Selects whether the combo box user input routine should assume that the list box
+contains literal strings, that can be fetched via C<get_item_text> ( see
+L<Prima::Lists> ). An example when this property is set to 0 is
+C<Prima::ColorComboBox> from the L<Prima::ComboBox> package.
 
 Default value: 1
 
 =item style INTEGER
 
-Selected one of three styles:
+Selects one of three styles of the combo box:
 
 =over
 
 =item cs::Simple
 
-The listbox is always visible, and the drop-down button is not.
+The list box is always visible, but the drop-down button is not.
 
 =item cs::DropDown
 
-The listbox is not visible, but the drop-down button is. When the
-use presses the drop-down button, the listbox is shown; when the list-box
+The list box is not visible, but the drop-down button is. When the
+user presses the drop-down button, the list box is shown; when the list-box
 is defocused, it gets hidden.
 
 =item cs::DropDownList
 
-Same as C<cs::DropDown>, but the user is restricted in the selection:
-the input line can only accept user input that is contained in listbox.
-If L<literal> set to 1, the auto completion feature is provided.
+Same as C<cs::DropDown> but the user is restricted in selection:
+the input line can only accept user input that is present in the list box.
+If L<literal> is set to 1, the auto-completion feature is provided.
 
 =back
 
 =item text STRING
 
-Mapped onto the edit widget's C<text> property.
+Alias of the input line's C<text> property.
 
 =back
 
@@ -928,14 +928,13 @@ Mapped onto the edit widget's C<text> property.
 
 =item Change
 
-Triggered with ComboBox value is changed.
+Triggered the value is changed.
 
 =item List events
 
 ComboBox forwards C<SelectItem> and C<DrawItem> events from the list box, and
 these are executed in the List's context (therefore $self there is not
-ComboBox, but the ComboBox->List). If you use C<SelectItem> you probably need
-C<Change> instead.
+ComboBox, but the ComboBox->List).
 
 See more in L<Prima::Lists>.
 
diff --git a/Prima/Const.pm b/Prima/Const.pm
index 45ac82c98..04534d421 100644
--- a/Prima/Const.pm
+++ b/Prima/Const.pm
@@ -313,18 +313,18 @@ Prima::Const - predefined constants
 
 =head1 DESCRIPTION
 
-C<Prima::Const> and L<Prima::Classes> is a minimal set of perl modules needed for
+C<Prima::Const> and L<Prima::Classes> for a minimal set of perl modules needed for
 the toolkit. Since the module provides bindings for the core constants, it is required
 to be included in every Prima-related module and program.
 
-The constants are assembled under the top-level package names, with no C<Prima::>
+The constants are collected under the top-level package names, with no C<Prima::>
 prefix. This violates the perl guidelines about package naming, however, it was
-considered way too inconvenient to prefix every constant with C<Prima::> string.
+considered way too inconvenient to prefix every constant with a C<Prima::> string.
 
-This document provides description of all core-coded constants. The constants
-are also described in the articles together with the corresponding methods and
-properties. For example, C<nt> constants are also described in L<Prima::Object/Flow>
-article.
+This document describes all constants defined in the core. The constants are
+also described in the articles together with the corresponding methods and
+properties. For example, the C<nt> constants are also described in the
+L<Prima::Object/Flow> article.
 
 =head1 API
 
@@ -544,7 +544,7 @@ See L<Prima::Widget/pointerType>
 
 =head2 dbt::  - device bitmap types
 
-        dbt::Bitmap                 monochrome 1 bit bitmap
+        dbt::Bitmap                 monochrome 1-bit bitmap
         dbt::Pixmap                 bitmap compatible with display format
         dbt::Layered                bitmap compatible with display format with alpha channel
 
@@ -568,13 +568,13 @@ Returns a C<cr::> constant corresponding to the C<ACTION>
 
 =item to_one_action ACTIONS
 
-Selects a best single action from combination of allowed C<ACTIONS>
+Selects the best single action from a combination of allowed C<ACTIONS>
 
 =item keymod ACTION
 
-Returns a C<km::> keyboard modifier constant the C<ACTION> will be expected to
-start on if the user presses that modifier during a DND session. Returns 0 for
-C<dnd::Copy> that is the standard action to be performed without any modifiers.
+Returns a C<km::> keyboard modifier constant that would initiate C<ACTION> 
+if the user presses it during a DND session. Returns 0 for
+C<dnd::Copy> which is the standard action to be performed without any modifiers.
 
 =back
 
@@ -679,22 +679,22 @@ See L<Prima::Drawable/fillPattern>
 
 =item builtin $FILL_PATTERN
 
-Given a result from C<Drawable::fillPattern>, a 8x8 array of integers, checks whether the array matches
+Given a result from C<Drawable::fillPattern>, an 8x8 array of integers, checks whether the array matches
 one of the builtin C<fp::> constants, and returns one if found. Returns undef otherwise.
 
 =item is_empty $FILL_PATTERN
 
-Given a result from C<Drawable::fillPattern>, a 8x8 array of integers, checks whether the array consists
-strictly of zeros, or not.
+Given a result from C<Drawable::fillPattern>, an 8x8 array of integers, checks if the array is
+all zeros
 
 =item is_solid $FILL_PATTERN
 
-Given a result from C<Drawable::fillPattern>, a 8x8 array of integers, checks whether the array consists
-strictly of ones, or not.
+Given a result from C<Drawable::fillPattern>, an 8x8 array of integers, checks if the array is
+all ones (ie 0xff)
 
 =item patterns
 
-Returns set of string-encoded fill patterns that correspond to builtin C<fp::> constants.
+Returns a set of string-encoded fill patterns that correspond to the builtin C<fp::> constants.
 These are not suitable for use in C<Drawable::fillPatterns>.
 
 =back
@@ -759,16 +759,16 @@ See L<Prima::Widget/growMode>
 =item Basic constants
 
 	gm::GrowLoX	widget's left side is kept in constant
-			distance from owner's right side
+			distance from the owner's right side
 	gm::GrowLoY	widget's bottom side is kept in constant
-			distance from owner's top side
+			distance from the owner's top side
 	gm::GrowHiX	widget's right side is kept in constant
-			distance from owner's right side
+			distance from the owner's right side
 	gm::GrowHiY	widget's top side is kept in constant
-			distance from owner's top side
-	gm::XCenter	widget is kept in center on its owner's
+			distance from the owner's top side
+	gm::XCenter	widget is kept in the center on its owner's
 			horizontal axis
-	gm::YCenter	widget is kept in center on its owner's
+	gm::YCenter	widget is kept in the center on its owner's
 			vertical axis
 	gm::DontCare	widgets origin is constant relative
 			to the screen
@@ -919,13 +919,13 @@ See L<Prima::Image/conversion>.
 	ict::Posterization   - no dithering, with palette optimized by the source pixels
 	ict::Ordered         - 8x8 ordered halftone dithering
 	ict::ErrorDiffusion  - error diffusion dithering with a static palette
-	ict::Optimized       - error diffusion dithering with optimized palette
+	ict::Optimized       - error diffusion dithering with an optimized palette
 
 Their values are combinations of C<ictp::> and C<ictd::> constants, see below.
 
 =head2 ictd:: - image conversion types, dithering
 
-These constants select color correction (dithering) algorithm when downsampling
+These constants select the color correction (dithering) algorithm when downsampling
 an image
 
 	ictd::None            - no dithering, pure colors only
@@ -937,13 +937,13 @@ an image
 These constants select how the target palette is made up when downsampling an image.
 
 	ictp::Unoptimized  - use whatever color mapping method is fastest,
-	                     image quality can be severely compromized
+	                     image quality can be severely compromised
 	ictp::Cubic        - use static cubic palette; a bit slower,
 	                     guaranteed mediocre quality
 	ictp::Optimized    - collect available colors in the image;
-	                     slowest, gives best results
+	                     slowest, gives the best results
 
-Not all combination of ictp and ictd constants are valid
+Not all combinations of ictp and ictd constants are valid
 
 =head2 is::  - image statistics indices
 
@@ -960,13 +960,13 @@ See L<Prima::Image/stats>.
 =head2 ist:: - image scaling types
 
 	ist::None      - image stripped or padded with zeros
-	ist::Box       - image will be scaled using a simple box transform
+	ist::Box       - the image will be scaled using a simple box transform
 	ist::BoxX      - columns behave as ist::None, rows as ist::Box
 	ist::BoxY      - rows behave as in ist::None, columns as ist::Box
 	ist::AND       - shrunken pixels AND-end together (black-on-white images)
 	ist::OR        - shrunken pixels OR-end together (white-on-black images)
 	ist::Triangle  - bilinear interpolation
-	ist::Quadratic - 2rd order (quadratic) B-Spline approximation of the Gaussian
+	ist::Quadratic - 2nd order (quadratic) B-Spline approximation of the Gaussian
 	ist::Sinc      - sine function
 	ist::Hermite   - B-Spline interpolation
 	ist::Cubic     - 3rd order (cubic) B-Spline approximation of the Gaussian
@@ -1124,16 +1124,16 @@ See also L<Prima::Window/modalResult>, L<Prima::Button/modalResult>.
 	ps::Enabled     - can both draw and get/set graphical properties on an object
 	ps::Information - can only get/set graphical properties on an object
 
-For brevity, ps::Disabled is equal to 0 so this allows for simple boolean testing whether one can
+For brevity, ps::Disabled is equal to 0 so this allows for simple boolean testing if one can
 get/set graphical properties on an object.
 
 See L<Drawable/get_paint_state>.
 
 =head2 rgn:: - result of Prima::Region.rect_inside
 
-	rgn::Inside
-	rgn::Outside    - rectangle is fully outside the region
-	rgn::Partially
+	rgn::Inside     - the rectangle is fully inside the region
+	rgn::Outside    - the rectangle is fully outside the region
+	rgn::Partially  - the rectangle overlaps the region but is not fully inside
 
 =head2 rgnop:: - Prima::Region.combine set operations
 
@@ -1182,7 +1182,7 @@ See L<Prima::Drawable/Raster operations>
         rop::DstAtop     # = dst srcA + src ( 1 - dstA )
 
         rop::Blend       # src + dst (1 - srcA)
-	                 # same as rop::SrcOver but assumes premultiplied source
+	                 # same as rop::SrcOver but assumes the premultiplied source
 
         rop::PorterDuffMask - masks out all bits but the constants above
 
@@ -1220,15 +1220,15 @@ ROP functions
 
 =item alpha ROP, SRC_ALPHA = undef, DST_ALPHA = undef
 
-Combines one of the alpha-supporting ROPs ( Porter-Duff snd Photoshop
-operators) with
-source and destination alpha, if defined, and returns new ROP constant. This is useful
-when blending with constant alpha is required with/over images that don't have their own
-alpha channel. Or as an additional alpha channel when using icons.
+Combines one of the alpha-supporting ROPs ( Porter-Duff and Photoshop
+operators) with source and destination alpha, if defined, and returns a new ROP
+constant. This is useful when blending with constant alpha is required
+with/over images that don't have their own alpha channel. Or as an additional
+alpha channel when using icons.
 
 =item blend ALPHA
 
-Creates a ROP that would effecively execute alpha blending of the source image
+Creates a ROP that would effectively execute alpha blending of the source image
 over the destination image with ALPHA value.
 
 =back
@@ -1288,16 +1288,16 @@ C<Widget::scroll> returns one of these.
 
 See also L<Prima::Application/get_system_value>
 
-	sv::YMenu            - height of menu bar in top-level windows
-	sv::YTitleBar        - height of title bar in top-level windows
+	sv::YMenu            - the height of the menu bar in top-level windows
+	sv::YTitleBar        - the height of the title bar in top-level windows
 	sv::XIcon            - width and height of main icon dimensions,
 	sv::YIcon              acceptable by the system
 	sv::XSmallIcon       - width and height of alternate icon dimensions,
 	sv::YSmallIcon         acceptable by the system
 	sv::XPointer         - width and height of mouse pointer icon
 	sv::YPointer           acceptable by the system
-	sv::XScrollbar       - width of the default vertical scrollbar
-	sv::YScrollbar       - height of the default horizontal scrollbar
+	sv::XScrollbar       - the width of the default vertical scrollbar
+	sv::YScrollbar       - the height of the default horizontal scrollbar
 	sv::XCursor          - width of the system cursor
 	sv::AutoScrollFirst  - the initial and the repetitive
 	sv::AutoScrollNext     scroll timeouts
@@ -1346,7 +1346,7 @@ Used in: L<Prima::InputLine>, L<Prima::ImageViewer>, L<Prima::Label>.
 
 =head2 to::  - text output constants
 
-These constants are used in various text and glyph related functions, 
+These constants are used in various text- and glyph-related functions
 and form a somewhat vague group of bit values that may or may not be used together
 depending on the function
 
@@ -1368,9 +1368,9 @@ See L<Prima::Drawable/text_wrap>
 
 	tw::CalcMnemonic          - calculates tilde underline position
 	tw::CollapseTilde         - removes escaping tilde from text
-	tw::CalcTabs              - wraps text with respect to tab expansion
+	tw::CalcTabs              - wraps the text with respect to tab expansion
 	tw::ExpandTabs            - expands tab characters
-	tw::BreakSingle           - determines if text is broken to single
+	tw::BreakSingle           - determines if the text is broken into single
 	                            characters when text cannot be fit
 	tw::NewLineBreak          - breaks line on newline characters
 	tw::SpaceBreak            - breaks line on space or tab characters
@@ -1379,7 +1379,7 @@ See L<Prima::Drawable/text_wrap>
 	                            text chunks
 	tw::WordBreak             - defines if text break by width goes by the
 	                            characters or by the words
-	tw::ReturnFirstLineLength - returns length of the first wrapped line
+	tw::ReturnFirstLineLength - returns the length of the first wrapped line
 	tw::Default               - tw::NewLineBreak | tw::CalcTabs | tw::ExpandTabs |
 	                            tw::ReturnLines | tw::WordBreak
 
diff --git a/Prima/DetailedList.pm b/Prima/DetailedList.pm
index ca93e5572..d217f4454 100644
--- a/Prima/DetailedList.pm
+++ b/Prima/DetailedList.pm
@@ -466,8 +466,8 @@ sub autoWidth { 0;}
 
 =head1 NAME
 
-Prima::DetailedList - a multi-column list viewer with a controlling
-header widget.
+Prima::DetailedList - multi-column list viewer with controlling
+header widget
 
 =head1 SYNOPSIS
 
@@ -491,16 +491,16 @@ use Prima::DetailedList;
 
 =head1 DESCRIPTION
 
-Prima::DetailedList is a descendant of Prima::ListViewer, and as such provides
-a certain level of abstraction. It overloads format of L<items> in order to
+Prima::DetailedList is a descendant of Prima::ListViewer and as such also provides
+a certain level of abstraction. It overloads the format of L<items> in order to
 support multi-column ( 2D ) cell span. It also inserts L<Prima::Widget::Header> widget
-on top of the list, so the user can interactively move, resize and sort the content
-of the list. The sorting mechanism is realized inside the package; it is
+on top of the list so that the user can interactively move, resize, and sort the content
+of the list. The sorting mechanism is also realized inside the package; it can be
 activated by the mouse click on a header tab.
 
-Since the class inherits Prima::ListViewer, some functionality, like 'item search by
-key', or C<get_item_text> method can not operate on 2D lists. Therefore, L<mainColumn>
-property is introduced, that selects the column representing all the data.
+Since the class inherits from Prima::ListViewer, some functionality, like 'item search by
+key', or C<get_item_text> method can not operate on 2D lists. Therefore, the L<mainColumn>
+property is introduced, that selects the column representing the textual data.
 
 =head1 API
 
@@ -510,17 +510,17 @@ property is introduced, that selects the column representing all the data.
 
 =item Sort COLUMN, DIRECTION
 
-Called inside L<sort> method, to facilitate custom algorithms of sorting.
-If the callback procedure is willing to sort by COLUMN index, then it must
-call C<clear_event>, to signal the event flow stop. The DIRECTION is a boolean
-flag, specifying whether the sorting must be performed is ascending ( 1 ) or
-descending ( 0 ) order.
+Called inside the L<sort> method to facilitate custom sorting algorithms.  If
+the callback procedure is willing to sort by COLUMN index, then it must call
+C<clear_event> to signal that the event flow must stop. The DIRECTION is a
+boolean flag, specifying whether the sorting must be performed in ascending ( 1
+) or descending ( 0 ) order.
 
 The callback procedure must operate on the internal storage of C<{items}>,
 which is an array of arrays of scalars.
 
-The default action is the literal sorting algorithm, where precedence is
-arbitrated by C<cmp> operator ( see L<perlop/"Equality Operators"> ) .
+The default action is the literal sorting algorithm where the precedence is
+arbitrated by the C<cmp> operator ( see L<perlop/"Equality Operators"> ) .
 
 =back
 
@@ -530,19 +530,20 @@ arbitrated by C<cmp> operator ( see L<perlop/"Equality Operators"> ) .
 
 =item aligns ARRAY
 
-Array of C<ta::> align constants, where each defined the column alignment.
-Where an item in the array is undef, it means that the value of the C<align> property must be used.
+An array of the C<ta::> align constants where each defines the column
+alignment.  If an item in the array is undef, it means that the value of the
+C<align> property must be used.
 
 =item columns INTEGER
 
-Governs the number of columns in L<items>. If set-called, and the new number
+Manages the number of columns in L<items>. If set-called, and the new number
 is different from the old number, both L<items> and L<headers> are restructured.
 
 Default value: 0
 
 =item headerClass
 
-Assigns a header class.
+Assigns the header class.
 
 Create-only property.
 
@@ -550,31 +551,31 @@ Default value: C<Prima::Widget::Header>
 
 =item headerProfile HASH
 
-Assigns hash of properties, passed to the header widget during the creation.
+Assigns a hash of properties passed to the header widget during the creation.
 
 Create-only property.
 
 =item headerDelegations ARRAY
 
-Assigns a header widget list of delegated notifications.
+Assigns list of delegated notifications to the header widget.
 
 Create-only property.
 
 =item headers ARRAY
 
-Array of strings, passed to the header widget as column titles.
+An array of strings passed to the header widget as column titles.
 
 =item items ARRAY
 
-Array of arrays of scalars, of arbitrary kind. The default
+An array of arrays of scalars of any kind. The default
 behavior, however, assumes that the scalars are strings.
 The data direction is from left to right and from top to bottom.
 
 =item mainColumn INTEGER
 
-Selects the column, responsible for representation of all the data.
-As the user clicks the header tab, C<mainColumn> is automatically
-changed to the corresponding column.
+Selects the column responsible for textual representation of all the data. When
+the user clicks a header tab C<mainColumn> is automatically changed to the
+corresponding column.
 
 Default value: 0
 
@@ -589,12 +590,11 @@ Default value: 0
 Sorts items by the COLUMN index in ascending order. If COLUMN is not specified,
 sorts by the last specified column, or by #0 if it is the first C<sort> invocation.
 
-If COLUMN was specified, and the last specified column equals to COLUMN,
+If the COLUMN was specified, and the last specified column equals to COLUMN,
 the sort direction is reversed.
 
-The method does not perform sorting itself, but invokes L<Sort> notification,
-so the sorting algorithms can be overloaded, or be applied differently to
-the columns.
+The method does not perform sorting itself, but calls the L<Sort> notification,
+so that the sorting algorithms can be customized.
 
 =back
 
diff --git a/Prima/DetailedOutline.pm b/Prima/DetailedOutline.pm
index c1285e96e..bed116a4c 100644
--- a/Prima/DetailedOutline.pm
+++ b/Prima/DetailedOutline.pm
@@ -372,9 +372,10 @@ and Prima::DetailedList.
 
 =head1 API
 
-This class inherits all the properties, methods, and events of Prima::OutlineViewer
-(primary ancestor) and Prima::DetailedList (secondary ancestor).  One new property
-is introduced, and one property is different enough to warrant mention.
+This class inherits all the properties, methods, and events of
+Prima::OutlineViewer (primary ancestor) and Prima::DetailedList (secondary
+ancestor).  One new property C<autoRecalc> is introduced, and the C<items>
+property is different enough to warrant the mention.
 
 =head2 Methods
 
@@ -384,7 +385,7 @@ is introduced, and one property is different enough to warrant mention.
 
 Each item is represented by an arrayref with either one or two elements.  The
 first element is the item data, an arrayref of text strings to display.  The
-second element, if present, is an arrayref of child items.
+second element, if present, is an arrayref of children.
 
 When using the node functionality inherited from Prima::OutlineViewer, the
 item data (that is, the arrayref of text strings) is the first element of the
diff --git a/Prima/DockManager.pm b/Prima/DockManager.pm
index 6b77f5664..6a6a78c8e 100644
--- a/Prima/DockManager.pm
+++ b/Prima/DockManager.pm
@@ -761,7 +761,7 @@ sub windowState
 {
 	my ( $self, $ws) = @_;
 	if ( $ws == ws::Minimized) {
-	for ( @{$self->{panels}}, @{$self-> {toolbars}}) {
+		for ( @{$self->{panels}}, @{$self-> {toolbars}}) {
 			next if $_-> dock;
 			my $e = $_-> externalDocker;
 			next unless $e;
@@ -1014,31 +1014,30 @@ Prima::DockManager - advanced dockable widgets
 =head1 DESCRIPTION
 
 C<Prima::DockManager> contains classes that implement additional
-functionality within the dockable widgets paradigm.
+functionality in the dockable widgets paradigm.
 
 The module introduces two new dockable widget classes:
-C<Prima::DockManager::Panelbar>, a general purpose
-dockable container for variable-sized widgets; and C<Prima::DockManager::Toolbar>,
-a dockable container for fixed-size command widgets, mostly push buttons.
-The command widgets, nested in a toolbar, can also be docked.
-
-C<Prima::DockManager> class is an application-oriented class in a way
-that ( mostly ) the only instance of it is needed in the program. It
-is derived from C<Prima::Component> and therefore is never visualized.
-The class instance is stored in C<instance> property of all module classes
-to serve as a docking hierarchy root. Through the document, I<instance>
-term is referred to C<Prima::DockManager> class instance.
+C<Prima::DockManager::Panelbar>, a general-purpose dockable container for
+variable-sized widgets; and C<Prima::DockManager::Toolbar>, a dockable
+container for fixed-size command widgets, mostly push buttons.  The command
+widgets nested in a toolbar can also be docked.
+
+The C<Prima::DockManager> class is application-oriented in a way that a
+single of it is needed. It is derived from C<Prima::Component> and therefore is
+never visualized.  The class instance is stored in the C<instance> property in all
+module classes to serve as a docking hierarchy root. Through the document,
+the I<instance> term means the C<Prima::DockManager> class instance.
 
 The module by itself is not enough to make a docking-aware application work
-effectively. The reader is urged to look at F<examples/dock.pl>
+effectively. The reader is urged to look at the F<examples/dock.pl>
 example code, which demonstrates the usage and capabilities of
 the module.
 
 =head1 Prima::DockManager::Toolbar
 
-A toolbar widget class. The toolbar has a dual nature; it can dock
-and accept docking widgets simultaneously. In the scope of C<Prima::DockManager>,
-the toolbar hosts command widget, mostly push buttons.
+A toolbar widget class. The toolbar has a dual nature; it can both dock itself
+and accept dockable widgets. As a dock, toolbars can host command widgets, mostly
+push buttons.
 
 The toolbar consists of two widgets. The external dockable widget is
 implemented in C<Prima::DockManager::Toolbar>, and the internal dock
@@ -1050,13 +1049,13 @@ in C<Prima::DockManager::ToolbarDocker> classes.
 
 =item autoClose BOOLEAN
 
-Selects the behavior of a toolbar when all of its command widgets are
-undocked. If 1, the toolbar is automatically destroyed. If 0
+Selects the behavior of the toolbar when all of its command widgets are
+undocked. If 1 (default), the toolbar is automatically destroyed. If 0
 it calls C<visible(0)>.
 
 =item childDocker WIDGET
 
-Pointer to C<Prima::DockManager::ToolbarDocker> instance.
+Pointer to the C<Prima::DockManager::ToolbarDocker> instance.
 
 See also C<Prima::DockManager::ToolbarDocker::parentDocker>.
 
@@ -1068,10 +1067,9 @@ C<Prima::DockManager> instance, the docking hierarchy root.
 
 =head1 Prima::DockManager::ToolbarDocker
 
-Internal class, implements a dock widget for command widgets,
-while serves as a client in a dockable toolbar, which is
-a C<Prima::LinearDockerShuttle> descendant. When its size is
-changed due an eventual rearrange of its docked widgets, also resizes
+An internal class, implements the dock widget for command widgets, and a client
+in a dockable toolbar, a C<Prima::LinearDockerShuttle> descendant. When its
+size is changed due to an eventual rearrangement of its docked widgets, also resizes
 the toolbar.
 
 =head2 Properties
@@ -1080,12 +1078,12 @@ the toolbar.
 
 =item instance INSTANCE
 
-C<Prima::DockManager> instance, the docking hierarchy root.
+The C<Prima::DockManager> instance, the docking hierarchy root.
 
 =item parentDocker WIDGET
 
-Pointer to C<Prima::DockManager::Toolbar> instance. When in
-the docked state, C<parentDocker> value is always equals to C<owner>.
+Pointer to a C<Prima::DockManager::Toolbar> instance. When in
+the docked state, the C<parentDocker> value is always equal to C<owner>.
 
 See also C<Prima::DockManager::Toolbar::childDocker>.
 
@@ -1102,19 +1100,20 @@ and returns its extensions.
 
 =item update_size
 
-Called when size is changed to resizes the owner widget. If it is in the docked
-state, the size change might result in change of position or docking state.
+Called when the size is changed to resize the owner widget. If the toolbar is
+docked, the change might result in a change of its position or docking
+state.
 
 =back
 
 =head1 Prima::DockManager::Panelbar
 
 The class is derived from C<Prima::LinearDockerShuttle>, and
-is different only in that C<instance> property is introduced,
+is different only in that the C<instance> property is introduced,
 and the external shuttle can be resized interactively.
 
 The class is to be used as a simple host to sizeable widgets.
-The user can dispose of the panel bar by clicking close button
+The user can dispose of the panel bar by clicking the close button
 on the external shuttle.
 
 =head2 Properties
@@ -1123,52 +1122,46 @@ on the external shuttle.
 
 =item instance INSTANCE
 
-C<Prima::DockManager> instance, the docking hierarchy root.
+The C<Prima::DockManager> instance, the docking hierarchy root.
 
 =back
 
 =head1 Prima::DockManager
 
-A binder class, contains set of functions that groups
-toolbars, panels, and command widgets together under the docking
-hierarchy.
-
-The manager servers several purposes.
-First, it is a command state holder: the command
-widgets, mostly buttons, usually are in enabled or disabled state in different
-life stages of a program. The manager maintains the enabled/disabled state
-by assigning each command an unique scalar value ( farther and in the
-code referred as I<CLSID> ). The toolbars can be created with set of
-command widgets, referred via these CLSIDs. The same is valid for
-the panels - although they do not host command widgets, the widgets that
-they do host can also be created indirectly via CLSID identifier.
-In addition to CLSID, the commands can be grouped by sections.
+A binder class, contains a set of functions that groups toolbars, panels, and
+command widgets together under the docking hierarchy.
+
+The manager serves several purposes.  First, it is a command state holder: the
+command widgets, mostly buttons, usually are in an enabled or disabled state in
+different life stages of a program. The manager maintains the enabled/disabled
+state by assigning each command a unique scalar value, or a I<CLSID>.
+The toolbars can be created using a set of command widgets, using these
+CLSIDs. The same is valid for the panels - although they do not host command
+widgets, the widgets that they do host can also be created indirectly via CLSID
+identifier.  In addition to CLSIDs, the commands can be grouped by sections.
 Both CLSID and group descriptor scalars are defined by the programmer.
 
-Second, C<create_manager> method presents a standard configuration
-widget, that allows rearranging of normally non-dockable command widgets,
-by presenting a full set of available commands to the user as icons.
-Dragging the icons to toolbars, dock widgets or merely outside the
-configuration widget automatically creates the corresponding command widget.
-The notable moment here is that the command widgets are not required
-to know anything about dragging and docking; any C<Prima::Widget>
-descendant can be used as a command widget.
-
-Third, it helps maintaining the toolbars and panels visibility
-when the main window is hidden or restored. C<windowState> method
+Second, the C<create_manager> method presents the standard launchpad interface
+that allows the rearranging of normally non-dockable command widgets, by presenting
+a full set of available commands to the user as icons.  Dragging the icons to
+toolbars, dock widgets, or merely outside the configuration widget
+automatically creates the corresponding command widget.  The notable moment
+here is that the command widgets are not required to know anything about
+dragging and docking; any C<Prima::Widget> descendant can be used as a command
+widget.
+
+Third, it helps maintain the toolbars' and panels' visibility
+when the main window is hidden or restored. The C<windowState> method
 hides or shows the toolbars and panels effectively.
 
-Fourth, it serves as a docking hierarchy root. All docking sessions
-begin from C<Prima::DockManager> object, which although does not provide
-docking capabilities itself ( it is C<Prima::Component> descendant ),
-redirects the docking requests to the lower-level dock widgets.
+Fourth, it serves as a docking hierarchy root. All docking sessions start their
+protocol interactions at a C<Prima::DockManager> object, which although does
+not provide docking capabilities itself ( it is a C<Prima::Component> descendant
+), redirects the docking requests to the children dock widgets.
 
-Fifth, it provides number of helper methods and notifications,
-and enforces use or C<fingerprint> property by all dockable widgets.
-This property has default value of C<0xFFFF> ( defined in C<Prima::Docks> ).
-The module contains the fingerprint C<dmfp::XXX> constants with value greater than this,
-so the toolbars and panels are not docked to a dock widget with the default
-configuration. The base constant set is:
+Finally, it provides several helper methods and notifications
+and enforces the use of the C<fingerprint> property by all dockable widgets.
+The module defines the following fingerprint C<dmfp::XXX> constants:
 
 	fdmp::Tools      ( 0x0F000) - dock the command widgets
 	fdmp::Toolbar    ( 0x10000) - dock the toolbars
@@ -1183,25 +1176,23 @@ example.
 
 =item commands HASH
 
-A hash of boolean values, with keys of CLSID scalars.
-If value is 1, the command is available. If 0, the command
-is disabled. Changes to this property are reflected in the
-visible command widgets, which are enabled or disabled
-immediately. Also, C<CommandChange> notification is triggered.
+A hash of boolean values with keys of CLSID scalars, where if the value is 1,
+the command is available and is disabled otherwise. Changes to this property
+are reflected in the visible command widgets, which are enabled or disabled
+immediately. Also, the C<CommandChange> notification is triggered.
 
 =item fingerprint INTEGER
 
 The property is read-only, and always returns C<0xFFFFFFFF>,
-to allow landing for all dockable widgets. In case when a finer
+to allow landing to all dockable widgets. In case a finer
 granulation is needed, the default C<fingerprint> values of
 toolbars and panels can be reset.
 
 =item interactiveDrag BOOLEAN
 
-If 1, the command widgets can be interactively dragged,
-created and destroyed. This property is usually operated together
-with C<create_manager> widget. If 0, the command widgets
-cannot be dragged.
+If 1, the command widgets can be interactively dragged, created, and destroyed.
+This property is usually operated together with the C<create_manager> launchpad
+widget. If 0, the command widgets cannot be dragged.
 
 Default value: 0
 
@@ -1221,31 +1212,29 @@ the toolbars and panels attached to:
 
 =item auto_toolbar_name
 
-Returns an unique name for an automatically created
+Returns a unique name for an automatically created
 toolbar, like C<Toolbar1>, C<Toolbar2> etc.
 
 =item commands_enable BOOLEAN, @CLSIDs
 
-Enabled or disables commands from CLSIDs array.
-The changes are reflected in the visible command widgets, which
-are enabled or disabled immediately.
-Also, C<CommandChange> notification is triggered.
+Enables or disables commands from CLSIDs array.  The changes are reflected in
+the visible command widgets, which are enabled or disabled immediately.  Also,
+the C<CommandChange> notification is triggered.
 
 =item create_manager OWNER, %PROFILE
 
-Inserts two widgets into OWNER with PROFILE parameters:
-a listbox with command section groups, displayed as items, that usually correspond to
-the predefined toolbar names, and a notebook that displays the
-command icons. The notebook pages are interactively selected by the listbox
-navigation.
+Inserts two widgets into OWNER with PROFILE parameters: a list box with command
+section groups, displayed as items, that usually correspond to the predefined
+toolbar names, and a notebook that displays the command icons. The notebook
+pages can be interactively selected by the list box navigation.
 
-The icons, dragged from the notebook, behave as dockable widgets:
-they can be landed upon a toolbar, or any other dock widget, given
-it matches the C<fingerprint> ( by default C<dmfp::LaunchPad|dmfp::Toolbar|dmfp::Tools>).
-C<dmfp::LaunchPad> constant allows the recycling; if a widget is dragged
-back onto the notebook, it is destroyed.
+The icons dragged from the notebook, behave as dockable widgets: they can be
+landed on a toolbar, or any other dock widget, given it matches the
+C<fingerprint> ( by default C<dmfp::LaunchPad|dmfp::Toolbar|dmfp::Tools>).
+C<dmfp::LaunchPad> constant allows the recycling; if a widget is dragged back
+onto the notebook, it is destroyed.
 
-Returns two widgets, the listbox and the notebook.
+Returns the two widgets created, the list box and the notebook.
 
 PROFILE recognizes the following keys:
 
@@ -1254,44 +1243,44 @@ PROFILE recognizes the following keys:
 =item origin X, Y
 
 Position where the widgets are to be inserted.
-Default value is 0,0.
+The default value is 0,0.
 
 =item size X, Y
 
-Size of the widget insertion area. By default
-the widgets occupy all OWNER interior.
+Size of the widget insertion area. By default,
+the widgets occupy all OWNER interiors.
 
 =item listboxProfile PROFILE
 
-Custom parameters, passed to the listbox.
+Custom parameters passed to the list box.
 
 =item dockerProfile PROFILE
 
-Custom parameteres, passed to the notebook.
+Custom parameters passed to the notebook.
 
 =back
 
 =item create_panel CLSID, %PROFILE
 
-Creates a dockable panel of a previously registered CLSID
-by C<register_panel>. PROFILE recognizes the following keys:
+Spawns a dockable panel from a previously registered CLSID.
+PROFILE recognizes the following keys:
 
 =over
 
 =item profile HASH
 
-Hash of parameters, passed to C<create()> of the panel widget class.
-Before passing it is merged with the set of parameters, registered
-by C<register_panel>. The C<profile> hash takes the precedence.
+A hash of parameters passed to the C<new()> method of the panel widget class.
+Before passing it is merged with the set of parameters registered
+by C<register_panel>. The C<profile> hash takes precedence.
 
 =item dockerProfile HASH
 
-Constains extra options, passed to C<Prima::DockManager::Panelbar>
-widget. Before the usage it is merged with the set of parameters,
+Contains extra options passed to the C<Prima::DockManager::Panelbar>
+widget. Before passing it is merged with the set of parameters
 registered by C<register_panel>.
 
-NB: The C<dock> key here contains a reference to a desired dock widget.
-If C<dock> set to C<undef>, the panel is created in the non-docked state.
+Note: The C<dock> key contains a reference to the desired dock widget.
+If C<dock> is set to C<undef>, the panel is created in the non-docked state.
 
 =back
 
@@ -1301,31 +1290,30 @@ Example:
 		dockerProfile => { dock => $main_window }},
 		profile       => { backColor => cl::Green });
 
-
 =item create_tool OWNER, CLSID, X1, Y1, X2, Y2
 
-Inserts a command widget, previously registered with CLSID by C<register_tool>, into
-OWNER widget with X1 - Y2 coordinates. For automatic maintenance of
-enable/disable state of command widgets OWNER is expected to be a
-toolbar. If it is not, the maintenance must be performed separately,
-for example, by C<CommandChange> event.
+Inserts a command widget, previously registered with a CLSID by
+C<register_tool>, into OWNER widget at X1 - Y2 coordinates. For automatic
+maintenance of enabled/disabled states of command widgets, OWNER is expected to
+be a toolbar. If it is not, the maintenance must be performed separately, for
+example, by reacting to the C<CommandChange> event.
 
 =item create_toolbar %PROFILE
 
-Creates a new toolbar of C<Prima::DockManager::Toolbar> class.
+Creates a new toolbar of the C<Prima::DockManager::Toolbar> class.
 The following PROFILE options are recognized:
 
 =over
 
 =item autoClose BOOLEAN
 
-Sets C<autoClose> property of the toolbar.
+Manages the C<autoClose> property of the toolbar.
 
-Default value is 1 if C<name> options is set, 0 otherwise.
+The default value is 1 if the C<name> option is set, and 0 otherwise.
 
 =item dock DOCK
 
-Contain a reference to a desired DOCK widget. If C<undef>,
+Contains a reference to the desired DOCK widget. If C<undef>,
 the toolbar is created in the non-docked state.
 
 =item dockerProfile HASH
@@ -1333,32 +1321,32 @@ the toolbar is created in the non-docked state.
 Parameters passed to C<Prima::DockManager::Toolbar> as
 creation properties.
 
-NB: The C<dock> key here contains a reference to a desired dock widget.
-If C<dock> set to C<undef>, the panel is created in the non-docked state.
+Note: The C<dock> key contains a reference to the desired dock widget.
+If C<dock> is set to C<undef>, the panel is created in the non-docked state.
 
 =item rect X1, Y1, X2, Y2
 
-Selects rectangle of the C<Prima::DockManager::ToolbarDocker> instance
-in the dock widget ( if docked ) or the screen ( if non-docked ) coordinates.
+Manages geometry of the C<Prima::DockManager::ToolbarDocker> instance in
+the dock widget ( if docked ) or the screen ( if non-docked ) coordinates.
 
 =item toolbarProfile HASH
 
 Parameters passed to C<Prima::DockManager::ToolbarDocker> as
-creation properties.
+properties.
 
 =item vertical BOOLEAN
 
-Sets C<vertical> property of the toolbar.
+Sets the C<vertical> property of the toolbar.
 
 =item visible BOOLEAN
 
-Selects visibility state of the toolbar.
+Selects the visibility state of the toolbar.
 
 =back
 
 =item get_class CLSID
 
-Returns class record hash, registered under CLSID, or C<undef>
+Returns a class record hash, registered under a CLSID, or C<undef>
 if the class is not registered. The hash format contains
 the following keys:
 
@@ -1370,7 +1358,8 @@ Widget class
 
 =item profile HASH
 
-Creation parameters passed to C<create> when the widget is created.
+Creation parameters passed to C<new> when the corresponding widget is
+instantiated.
 
 =item tool BOOLEAN
 
@@ -1389,19 +1378,19 @@ Saved coordinates of the widget
 
 =item panel_by_id CLSID
 
-Return reference to a panel widget represented by CLSID scalar,
-or C<undef> if none found.
+Returns reference to the panel widget represented by CLSID scalar,
+or C<undef> if none is found.
 
 =item panel_menuitems CALLBACK
 
 A helper function; maps all panel names into a structure, ready to
-feed into C<Prima::AbstractMenu::items> property ( see L<Prima::Menu> ).
-The action member of the menu item record is set to CALLBACK scalar.
+feed into the C<Prima::AbstractMenu::items> property ( see L<Prima::Menu> ).
+The action member of the menu item record is set to the CALLBACK scalar.
 
 =item panel_visible CLSID, BOOLEAN
 
-Sets the visibility of a panel, referred by CLSID scalar.
-If VISIBLE is 0, a panel is destroyed; if 1, new panel instance
+Sets the visibility of a panel referred to by the CLSID scalar.
+If VISIBLE is 0, the panel is destroyed; if 1, a new panel instance
 is created.
 
 =item panels
@@ -1411,16 +1400,16 @@ Returns all visible panel widgets in an array.
 =item predefined_panels CLSID, DOCK, [ CLSID, DOCK, ... ]
 
 Accepts pairs of scalars, where each first item is a panel CLSID
-and second is the default dock widget. Checks for panel visibility,
+and the second is the default dock widget. Checks for the panel visibility
 and creates the panels that are not visible.
 
-The method is useful in program startup, when some panels
+The method is useful in a program startup, when some panels
 have to be visible from the beginning.
 
 =item predefined_toolbars @PROFILES
 
-Accepts array of hashes, where each array item describes a toolbar and
-a default set of command widgets. Checks for toolbar visibility,
+Accepts an array of hashes where each array item describes a toolbar and
+a default set of command widgets. Checks for the toolbar visibility
 and creates the toolbars that are not visible.
 
 The method recognizes the following PROFILES options:
@@ -1433,12 +1422,12 @@ The default dock widget.
 
 =item list ARRAY
 
-Array of CLSIDs corresponding to the command widgets to be inserted
+An array of CLSIDs corresponding to the command widgets to be inserted
 into the toolbar.
 
 =item name STRING
 
-Selects toolbar name.
+Selects the toolbar name.
 
 =item origin X, Y
 
@@ -1453,7 +1442,7 @@ have to be visible from the beginning.
 =item register_panel CLSID, PROFILE
 
 Registers a panel client class and set of parameters to be associated with
-CLSID scalar. PROFILE must contain the following keys:
+a CLSID scalar. PROFILE must contain the following keys:
 
 =over
 
@@ -1463,22 +1452,22 @@ Client widget class
 
 =item text STRING
 
-String, displayed in the panel title bar
+A string of text displayed in the panel title bar
 
 =item dockerProfile HASH
 
-Hash of parameters, passed to C<Prima::DockManager::Panelbar>.
+A hash of parameters passed to C<Prima::DockManager::Panelbar>.
 
 =item profile
 
-Hash of parameters, passed to the client widget.
+A hash of parameters passed to the client widget.
 
 =back
 
 =item register_tool CLSID, PROFILE
 
 Registers a control widget class and set of parameters to be associated with
-CLSID scalar. PROFILE must be set the following keys:
+a CLSID scalar. PROFILE must contain the following keys:
 
 =over
 
@@ -1488,19 +1477,19 @@ Client widget class
 
 =item profile HASH
 
-Hash of parameters, passed to the control widget.
+A hash of parameters passed to the control widget.
 
 =back
 
 =item toolbar_by_name NAME
 
-Returns a pointer to a toolbar of NAME, or C<undef> if none found.
+Returns a reference to the toolbar of NAME, or C<undef> if none is found.
 
 =item toolbar_menuitems CALLBACK
 
 A helper function; maps all toolbar names into a structure, ready to
-feed into C<Prima::AbstractMenu::items> property ( see L<Prima::Menu> ).
-The action member of the menu item record is set to CALLBACK scalar.
+feed into the C<Prima::AbstractMenu::items> property ( see L<Prima::Menu> ).
+The action member of the menu item record is set to the CALLBACK scalar.
 
 =item toolbar_visible TOOLBAR, BOOLEAN
 
@@ -1515,7 +1504,7 @@ Returns all toolbar widgets in an array.
 
 Mimics interface of C<Prima::Window::windowState>, and maintains
 visibility of toolbars and panels. If the parameter is C<ws::Minimized>,
-the toolbars and panels are hidden. On any other parameter these are shown.
+the toolbars and panels are hidden. On any other parameter, these are shown.
 
 To be used inside a callback code of a main window, that has the toolbars
 and panels attached to:
@@ -1530,14 +1519,14 @@ and panels attached to:
 
 =item Command CLSID
 
-A generic event, triggered by a command widget when the user activates
+A generic event triggered by a command widget when the user activates
 it. It can also be called by other means.
 
 CLSID is the widget identifier.
 
 =item CommandChange
 
-Called when C<commands> property changes or C<commands_enable> method is invoked.
+Called when the C<commands> property changes or the C<commands_enable> method is invoked.
 
 =item PanelChange
 
@@ -1545,13 +1534,13 @@ Triggered when a panel is created or destroyed by the user.
 
 =item ToolbarChange
 
-Triggered when a toolbar is created, shown, hidden, or destroyed  by the user.
+Triggered when a toolbar is created, shown, gets hidden, or destroyed by the user.
 
 =back
 
 =head1 Prima::DockManager::S::SpeedButton
 
-The package simplifies creation of C<Prima::SpeedButton> command widgets.
+The package simplifies the creation of C<Prima::SpeedButton> command widgets.
 
 =head2 Methods
 
@@ -1559,15 +1548,17 @@ The package simplifies creation of C<Prima::SpeedButton> command widgets.
 
 =item class IMAGE, CLSID, %PROFILE
 
-Builds a hash with parameters, ready to feed C<Prima::DockManager::register_tool>
-for registering a C<Prima::SpeedButton> class instance with PROFILE parameters.
+Builds a hash with parameters, ready to feed to
+C<Prima::DockManager::register_tool> for registering a combination of the
+C<Prima::SpeedButton> class and the PROFILE parameters.
 
-IMAGE is a path to a image file, loaded and stored in the registration hash.
-IMAGE provides an extended syntax for indicating a frame index, if the image file is multiframed: the frame index is appended to the path name
-with C<:> character prefix.
+IMAGE is the path to an image file, loaded and stored in the registration hash.
+IMAGE provides an extended syntax for selecting the frame index if the image file
+is multiframed: the frame index is appended to the path name with the C<:>
+character prefix.
 
-CLSID scalar is not used; it is returned so the method result can
-directly be passed into C<register_tool> method.
+CLSID scalar is not used but is returned so the method result can
+directly be passed into the C<register_tool> method.
 
 Returns two scalars: CLSID and the registration hash.
 
diff --git a/Prima/Docks.pm b/Prima/Docks.pm
index 3fa9b48f9..cc9cff94c 100644
--- a/Prima/Docks.pm
+++ b/Prima/Docks.pm
@@ -1,14 +1,3 @@
-# contains:
-#	AbstractDocker::Interface
-#		SimpleWidgetDocker
-#		ClientWidgetDocker
-#		LinearWidgetDocker
-#		FourPartDocker
-#	ExternalDockerShuttle
-#	InternalDockerShuttle
-#		LinearDockerShuttle
-#		SingleLinearWidgetDocker
-
 package Prima::Docks;
 
 use Prima;
@@ -1741,44 +1730,43 @@ Prima::Docks - dockable widgets
 
 =head1 DESCRIPTION
 
-The module contains a set of classes and an implementation of dockable widgets
-interface. The interface assumes two parties, the dockable widget
+The module contains a set of classes and an implementation of the dockable widgets
+interface. The interface assumes two parties, the dockable widget,
 and the dock widget; the generic methods for the dock widget class are contained in
-C<Prima::AbstractDocker::Interface> package.
+the C<Prima::AbstractDocker::Interface> package.
 
 =head1 USAGE
 
-A dockable widget is required to take particular steps before
-it can dock to a dock widget. It needs to talk to the dock and
-find out if it is allowed to land, or if the dock contains lower-level dock widgets
-that might suit better for docking. If there's more than one dock
-widget in the program, the dockable widget can select between the targets; this is
-especially actual when a dockable widget is dragged by mouse and
-the arbitration is performed on geometrical distance basis.
-
-The interface implies that there exists at least one tree-like hierarchy of dock widgets,
-linked up to a root dock widget. The hierarchy is not required to follow
-parent-child relationships, although this is the default behavior.
-All dockable widgets are expected to know explicitly what hierarchy tree they
-wish to dock to. C<Prima::InternalDockerShuttle> introduces C<dockingRoot> property
+A dockable widget is required to take particular steps before it may land on a
+dock widget. It needs to talk to the dock and find out if it is allowed to
+land, or if the dock contains children dock widgets that might suit better for
+the docking. If there's more than one dock widget in the program, the dockable
+widget can select between the targets; this is especially actual when a
+dockable widget is dragged by the mouse and the landing arbitration is based
+on geometrical distance.
+
+The interface implies that there exists at least one tree-like hierarchy of
+dock widgets, linked up to a root dock widget. The hierarchy is not required to
+follow parent-child relationships although this is the default behavior.  All
+dockable widgets are expected to know explicitly what hierarchy tree they wish
+to dock to. C<Prima::InternalDockerShuttle> introduces the C<dockingRoot> property
 for this purpose.
 
-The conversation between parties starts when a dockable widget
-calls C<open_session> method of the dock. The dockable widget passes
-set of parameters signaling if the widget is ready to change its size
-in case the dock widget requires so, and how. C<open_session> method can either refuse
-or accept the widget.
-In case of the positive answer from C<open_session>, the dockable widget
-calls C<query> method, which either returns a new rectangle, or another dock widget.
-In the latter case, the caller can enumerate all available dock widgets by
-repetitive calls to C<next_docker> method. The session is closed by C<close_session>
-call; after that, the widget is allowed to dock by setting its C<owner>
-to the dock widget, the C<rect> property to the negotiated position and size, and
-calling C<dock> method.
-
-C<open_session>/C<close_session> brackets are used to cache all necessary
-calculations once, making C<query> call as light as possible. This design allows
-a dockable widget, when dragged, repeatedly ask all reachable docks in an
+The conversation between parties starts when a dockable widget calls the
+C<open_session> method of the dock. The dockable widget passes a set of
+parameters signaling if the widget is ready to change its size in case the dock
+widget requires so, and how. The C<open_session> method can either refuse or accept
+the widget.  In case of the positive answer from C<open_session>, the dockable
+widget calls the C<query> method, which either returns a new rectangle or
+another dock widget.  In the latter case, the caller can enumerate all
+available dock widgets by repetitive calls to the C<next_docker> method. The
+session is closed by a C<close_session> call; after that, the widget is allowed
+to land by setting its C<owner> to the dock widget, the C<rect> property to the
+negotiated position and size, and finally calling the C<dock> method.
+
+The C<open_session>/C<close_session> brackets cache all necessary
+calculations once, making the C<query> call as light as possible. This design allows
+a dockable widget when dragged, to repeatedly ask all reachable docks in an
 optimized way. The docking sessions are kept open until the drag
 session is finished.
 
@@ -1808,77 +1796,74 @@ The conversation can be schematized in the following code:
 	$dock-> close_session( $session_id);
 
 Since even the simplified code is quite cumbersome, direct calls to
-C<open_session> are rare. Instead, C<Prima::InternalDockerShuttle>
-implements C<find_docking> method which performs the arbitration automatically
-and returns the appropriate dock widget.
-
-C<Prima::InternalDockerShuttle> is a class that implements dockable
-widget functionality. It also employs a top-level window-like wrapper widget
-for the dockable widget when it is not docked.
-By default, C<Prima::ExternalDockerShuttle> is used as the wrapper widget class.
-
-It is not required, however, to use neither C<Prima::InternalDockerShuttle>
-nor C<Prima::AbstractDocker::Interface> to implement a dockable widget;
-the only requirements to one is to respect C<open_session>/C<close_session>
+C<open_session> are rare. Instead, C<Prima::InternalDockerShuttle> implements
+the C<find_docking> method which performs the arbitration automatically and
+returns the appropriate dock widget.
+
+C<Prima::InternalDockerShuttle> is the class that implements the dockable
+widget functionality. It also provides a top-level window-like wrapper widget
+for the dockable widget that hosts the widget automatically if it is not
+docked.  By default, C<Prima::ExternalDockerShuttle> is used as the wrapper
+widget class.
+
+It is not required, however, to use either C<Prima::InternalDockerShuttle>
+or C<Prima::AbstractDocker::Interface> to implement a dockable widget;
+the only requirement is to respect the C<open_session>/C<close_session>
 protocol.
 
-C<Prima::InternalDockerShuttle> initiates a class hierarchy of dockable widgets.
-Its descendants are C<Prima::LinearWidgetDocker> and, in turn, C<Prima::SingleLinearWidgetDocker>.
-C<Prima::SimpleWidgetDocker> and C<Prima::LinearWidgetDocker>, derived from
-C<Prima::AbstractDocker::Interface>, begin hierarchy of dock widgets.
-The full hierarchy is as follows:
+The full hierarchy of widgets participating in the mechanism is as follows:
 
 	Prima::AbstractDocker::Interface
 		Prima::SimpleWidgetDocker
-		Prima::ClientWidgetDocker
+			Prima::ClientWidgetDocker
 		Prima::LinearWidgetDocker
+			Prima::SingleLinearWidgetDocker
 		Prima::FourPartDocker
 
 	Prima::InternalDockerShuttle
 		Prima::LinearDockerShuttle
-		Prima::SingleLinearWidgetDocker
 
 	Prima::ExternalDockerShuttle
 
 All docker widget classes are derived from C<Prima::AbstractDocker::Interface>.
 Depending on the specialization, they employ more or less sophisticated schemes
-for arranging dockable widgets inside. The most complicated scheme is implemented
-in C<Prima::LinearWidgetDocker>; it does not allow children overlapping and is
-able to rearrange with children and resize itself when a widget is docked or undocked.
+for arranging dockable widgets inside themselves. The most complicated scheme
+is implemented in C<Prima::LinearWidgetDocker>; it does not allow children to
+overlap, can rearrange the children, and resize itself when a widget is
+docked or undocked.
 
 The package provides only basic functionality. Module C<Prima::DockManager>
-provides common dockable controls, - toolbars, panels, speed buttons etc.
-based on C<Prima::Docks> module. See L<Prima::DockManager>.
+provides common dockable controls, - toolbars, panels, speed buttons, etc.
+based on the C<Prima::Docks> module. See L<Prima::DockManager>.
 
 =head1 Prima::AbstractDocker::Interface
 
 Implements generic functionality of a docket widget. The class is
 not derived from C<Prima::Widget>; is used as a secondary ascendant class
-for dock widget classes.
+for the dock widget classes.
 
 =head2 Properties
 
-Since the class is not C<Prima::Object> descendant, it provides
-only run-time implementation of its properties. It is up to the
-descendant object whether the properties are recognized on the creation stage
-or not.
+Since the class is not a C<Prima::Object> descendant, it provides only run-time
+implementation of its properties. It is up to the descendant object whether the
+properties are recognized during the creation stage or not.
 
 =over
 
 =item fingerprint INTEGER
 
-A custom bit mask, to be used by docking widgets to reject inappropriate
-dock widgets on early stage. The C<fingerprint> property is not part
-of the protocol, and is not required to be present in a dockable widget implementation.
+A custom bit mask used by docking widgets to reject inappropriate dock widgets
+at an early stage. The C<fingerprint> property is not a part of the protocol
+and is not required to be present in the implementation of a dockable widget.
 
 Default value: C<0x0000FFFF>
 
 =item dockup DOCK_WIDGET
 
-Selects the upper link in dock widgets hierarchy tree. The upper
-link is required to be a dock widget, but is not required to be
-a direct or an indirect parent. In this case, however, the maintenance
-of the link must be implemented separately, for example:
+Selects the upper link in the dock widgets hierarchy tree. The upper link is
+required to be a dock widget but is not required to be a direct or an indirect
+parent. In this case, however, the maintenance of the link must be implemented
+separately, for example:
 
 	$self-> dockup( $upper_dock_not_parent );
 
@@ -1900,12 +1885,12 @@ of the link must be implemented separately, for example:
 
 =item add_subdocker SUBDOCK
 
-Appends SUBDOCK to the list of lower-level docker widgets. The items of the list are
-returned by C<next_docker> method.
+Appends SUBDOCK to the list of children docker widgets. The items of the list are
+returned by the C<next_docker> method.
 
 =item check_session SESSION
 
-Debugging procedure; checks SESSION hash, warns if its members are
+A debugging procedure. Checks SESSION hash, and warns if its members are
 invalid or incomplete. Returns 1 if no fatal errors were encountered;
 0 otherwise.
 
@@ -1915,10 +1900,10 @@ Closes docking SESSION and frees the associated resources.
 
 =item dock WIDGET
 
-Called after WIDGET is successfully finished negotiation with
-the dock widget and changed its C<owner> property. The method
-adapts the dock widget layout and lists WIDGET into list of
-docked widgets. The method does not change C<owner> property of WIDGET.
+Called after WIDGET successfully finished negotiations with the dock widget and
+changed its C<owner> property. The method adapts the dock widget layout and
+lists the WIDGET into the list of docked widgets. The method does not change
+the C<owner> property of the WIDGET.
 
 The method must not be called directly.
 
@@ -1929,22 +1914,22 @@ and calling C<rearrange>.
 
 =item docklings
 
-Returns array of docked widgets.
+Returns an array of docked widgets
 
 =item next_docker SESSION, [ X, Y ]
 
-Enumerates lower-level docker widgets within SESSION; returns
+Enumerates children docker widgets inside the SESSION; returns
 one docker widget at a time. After the last widget returns
 C<undef>.
 
-The enumeration pointer is reset by C<query> call.
+The enumeration pointer is reset by the C<query> call.
 
-X and Y are coordinates of the point of interest.
+X and Y are the coordinates of the point of interest.
 
 =item open_session PROFILE
 
-Opens docking session with parameters stored in PROFILE
-and returns session ID scalar in case of success, or C<undef> otherwise.
+Opens a new docking session with parameters stored in the PROFILE hash.
+Returns a session ID scalar in case of success, or C<undef> otherwise.
 The following keys must be set in PROFILE:
 
 =over
@@ -1952,52 +1937,51 @@ The following keys must be set in PROFILE:
 =item position ARRAY
 
 Contains two integer coordinates of the desired position of
-a widget in (X,Y) format in screen coordinate system.
+a widget in (X,Y) format in the screen coordinate system.
 
 =item self WIDGET
 
-Widget that is about to dock.
+The widget that is about to dock.
 
 =item sizeable ARRAY
 
 Contains two boolean flags, representing if the widget can be resized
 to an arbitrary size, horizontally and vertically. The arbitrary resize
-option used as last resort if C<sizes> key does not contain the desired
+option is used as a last resort if the C<sizes> key does not contain the desired
 size.
 
 =item sizeMin ARRAY
 
-Two integers; minimal size that the widget can accept.
+Two integers; the minimal size that the widget can accept.
 
 =item sizes ARRAY
 
-Contains arrays of points in (X,Y) format; each point represents an
-acceptable size of the widget. If C<sizeable> flags are set to 0,
-and none of C<sizes> can be accepted by the dock widget, C<open_session>
+Contains an array of points in the (X,Y) format; each point represents an
+acceptable widget size. If both of the C<sizeable> flags are set to 0
+and none of the C<sizes> can be accepted by the dock widget, C<open_session>
 fails.
 
 =back
 
 =item query SESSION [ X1, Y1, X2, Y2 ]
 
-Checks if a dockable widget can be landed into the dock.
+Checks if a dockable widget can be landed on the dock.
 If it can, returns a rectangle that the widget must be set to.
 If coordinates ( X1 .. Y2 ) are specified, returns the
 rectangle closest to these. If C<sizes> or C<sizeable>
-keys of C<open_session> profile were set, the returned size
+keys of the C<open_session> profile were set, the returned size
 might be different from the current docking widget size.
 
-Once the caller finds the result appropriate, it is allowed to change
-its owner to the dock; after that, it must change its origin and size correspondingly
-to the result, and then call C<dock>.
+Once the caller finds the result appropriate, it is allowed to reparent under
+the dock; after that, it must change its origin and size correspondingly to the
+result, and then call C<dock>.
 
-If the dock cannot accept the widget, but contains lower-lever
-dock widgets, returns the first lower-lever widget. The caller
-can use subsequent calls to C<next_docker> to enumerate all
-lower-level dock widgets. A call to C<query>
-resets the internal enumeration pointer.
+If the dock cannot accept the widget but contains children dock widgets,
+returns the first child widget. The caller can use subsequent calls to
+C<next_docker> to enumerate all the children docks. A call to C<query> resets
+the internal enumeration pointer.
 
-If the widget cannot be landed, an empty array is returned.
+If the widget may not be landed, an empty array is returned.
 
 =item rearrange
 
@@ -2010,24 +1994,24 @@ but usually C<rearrange> is faster.
 
 =item redock_widget WIDGET
 
-Effectively re-docks the docked WIDGET. If WIDGET has C<redock>
+Effectively re-docks the docked WIDGET. If WIDGET has a C<redock>
 method in its namespace, it is called instead.
 
 =item remove_subdocker SUBDOCK
 
-Removes SUBDOCK from the list of lower-level docker widgets.
+Removes SUBDOCK from the list of children docker widgets.
 See also L<add_subdocker>.
 
 =item replace FROM, TO
 
-Assigns widget TO same owner and rectangle as FROM. The FROM widget
+Assigns the widget TO the same owner and size as FROM. The FROM widget
 must be a docked widget.
 
 =item undock WIDGET
 
-Removes WIDGET from list of docked widgets. The layout of the dock widget
-can be changed after execution of this method. The method does not
-change C<owner> property of WIDGET.
+Removes WIDGET from the list of docked widgets. The layout of the dock widget
+can be changed after the execution of this method. The method does not change
+the C<owner> property of WIDGET.
 
 The method must not be called directly.
 
@@ -2035,24 +2019,23 @@ The method must not be called directly.
 
 =head1 Prima::SimpleWidgetDocker
 
-A simple dock widget; accepts any widget that geometrically fits into.
+A simple dock widget; accepts any widget that geometrically fits into it.
 Allows overlapping of the docked widgets.
 
 =head1 Prima::ClientWidgetDocker
 
-A simple dock widget; accepts any widget that can be fit to cover all
+A simple dock widget; accepts any widget that can cover all
 dock's interior.
 
 =head1 Prima::LinearWidgetDocker
 
-A toolbar-like docking widget class. The implementation does
-not allow tiling, and can reshape the dock widget and rearrange
-the docked widgets if necessary.
+A toolbar-like docking widget class. The implementation does not allow tiling
+but can reshape the dock widget and rearrange the docked widgets if necessary.
 
-C<Prima::LinearWidgetDocker> is orientation-dependent; its main axis,
-managed by C<vertical> property, is used to align docked widgets in
-'lines', which in turn are aligned by the opposite axis ( 'major' and 'minor' terms
-are used in the code for the axes ).
+C<Prima::LinearWidgetDocker> is orientation-dependent; its main axis, managed
+by the C<vertical> property, aligns the docked widgets in 'lines', which in
+turn are aligned by the opposite axis ( 'major' and 'minor' terms are used in
+the code for the axes ).
 
 =head2 Properties
 
@@ -2060,8 +2043,8 @@ are used in the code for the axes ).
 
 =item growable INTEGER
 
-A combination of C<grow::XXX> constants, that describes how
-the dock widget can be resized. The constants are divided in two
+A combination of the C<grow::XXX> constants that describes how
+the dock widget can be resized. The constants are divided into two
 sets, direct and indirect, or, C<vertical> property independent and
 dependent.
 
@@ -2072,10 +2055,10 @@ The first set contains explicitly named constants:
 	grow::Right      grow::ForwardRight      grow::BackRight
 	grow::Up         grow::ForwardUp         grow::BackUp
 
-that select if the widget can be grown to the direction shown.
+that select if the widget can grow in the direction shown.
 These do not change meaning when C<vertical> changes, though they do
 change the dock widget behavior. The second set does not affect
-dock widget behavior when C<vertical> changes, however the names
+dock widget behavior when C<vertical> changes, however, the names
 are not that illustrative:
 
 	grow::MajorLess  grow::ForwardMajorLess  grow::BackMajorLess
@@ -2083,7 +2066,7 @@ are not that illustrative:
 	grow::MinorLess  grow::ForwardMinorLess  grow::BackMinorLess
 	grow::MinorMore  grow::ForwardMinorMore  grow::BackMinorMore
 
-C<Forward> and C<Back> prefixes select if the dock widget can be
+The C<Forward> and C<Back> prefixes select if the dock widget can be
 respectively expanded or shrunk in the given direction. C<Less> and
 C<More> are equivalent to C<Left> and C<Right> when C<vertical> is 0,
 and to C<Up> and C<Down> otherwise.
@@ -2095,11 +2078,11 @@ Default value: 0
 =item hasPocket BOOLEAN
 
 A boolean flag, affects the possibility of a docked widget to reside
-outside the dock widget inferior. If 1, a docked wigdet is allowed
+outside the dock widget inferior. If 1, a docked widget is allowed
 to stay docked ( or dock into a position ) further on the major axis
-( to the right when C<vertical> is 0, up otherwise ), as if there's
+( to the right when C<vertical> is 0, up otherwise ) as if there's
 a 'pocket'. If 0, a widget is neither allowed to dock outside the
-inferior, nor is allowed to stay docked ( and is undocked automatically )
+inferior nor is allowed to stay docked ( and is undocked automatically )
 when the dock widget shrinks so that the docked widget cannot stay in
 the dock boundaries.
 
@@ -2120,13 +2103,13 @@ Default value: 0
 
 =item Dock
 
-Called when C<dock> is successfully finished.
+Called when the C<dock> method is successfully finished.
 
 =item DockError WIDGET
 
-Called when C<dock> is unsuccessfully finished. This only
-happens if WIDGET does not follow the docking protocol, and inserts
-itself into a non-approved area.
+Called when the C<dock> method is unsuccessfully finished. This only happens if WIDGET
+does not follow the docking protocol, and inserts itself into a non-approved
+area.
 
 =item Undock
 
@@ -2136,15 +2119,17 @@ Called when C<undock> is finished.
 
 =head1 Prima::SingleLinearWidgetDocker
 
-Descendant of C<Prima::LinearWidgetDocker>. In addition
-to the constraints, introduced by the ascendant class,
-C<Prima::SingleLinearWidgetDocker> allows only one line ( or row,
-depending on C<vertical> property value ) of docked widgets.
+Descendant of C<Prima::LinearWidgetDocker>. In addition to the constraints
+introduced by the ascendant class, C<Prima::SingleLinearWidgetDocker> allows
+only one row ( or column, depending on the C<vertical> property value ) of docked
+widgets.
 
 =head1 Prima::FourPartDocker
 
-Implementation of a docking widget, with its four sides
-acting as 'rubber' docking areas.
+Implementation of a docking widget that hosts four children docker widgets on
+its sides and one in the center.  All of the children docks can grow and shrink
+automatically so that the whole setup has an effect as if the dock borders are
+dynamic.
 
 =head2 Properties
 
@@ -2152,109 +2137,109 @@ acting as 'rubber' docking areas.
 
 =item indents ARRAY
 
-Contains four integers, specifying the breadth of offset for
-each side. The first integer is width of the left side, the second - height
-of the bottom side, the third - width of the right side, the fourth - height
+Contains four integers specifying the breadth of offset for
+each side. The first integer is the width of the left side, the second - the height
+of the bottom side, the third is the width of the right side, and the fourth - height
 of the top side.
 
 =item dockerClassLeft STRING
 
-Assigns class of left-side dock window.
+Assigns the class of the left-side dock window.
 
 Default value: C<Prima::LinearWidgetDocker>.
 Create-only property.
 
 =item dockerClassRight STRING
 
-Assigns class of right-side dock window.
+Assigns the class of the right-side dock window.
 
 Default value: C<Prima::LinearWidgetDocker>.
 Create-only property.
 
 =item dockerClassTop STRING
 
-Assigns class of top-side dock window.
+Assigns the class of the top-side dock window.
 
 Default value: C<Prima::LinearWidgetDocker>.
 Create-only property.
 
 =item dockerClassBottom STRING
 
-Assigns class of bottom-side dock window.
+Assigns the class of the bottom-side dock window.
 
 Default value: C<Prima::LinearWidgetDocker>.
 Create-only property.
 
 =item dockerClassClient STRING
 
-Assigns class of center dock window.
+Assigns the class of the center dock window.
 
 Default value: C<Prima::ClientWidgetDocker>.
 Create-only property.
 
 =item dockerProfileLeft HASH
 
-Assigns hash of properties, passed to the left-side dock widget during the creation.
+Assigns a hash of properties, passed to the left-side dock widget during the creation.
 
 Create-only property.
 
 =item dockerProfileRight HASH
 
-Assigns hash of properties, passed to the right-side dock widget during the creation.
+Assigns a hash of properties, passed to the right-side dock widget during the creation.
 
 Create-only property.
 
 =item dockerProfileTop HASH
 
-Assigns hash of properties, passed to the top-side dock widget during the creation.
+Assigns a hash of properties, passed to the top-side dock widget during the creation.
 
 Create-only property.
 
 =item dockerProfileBottom HASH
 
-Assigns hash of properties, passed to the bottom-side dock widget during the creation.
+Assigns a hash of properties, passed to the bottom-side dock widget during the creation.
 
 Create-only property.
 
 =item dockerProfileClient HASH
 
-Assigns hash of properties, passed to the center dock widget during the creation.
+Assigns a hash of properties, passed to the center dock widget during the creation.
 
 Create-only property.
 
 =item dockerDelegationsLeft ARRAY
 
-Assigns the left-side dock list of delegated notifications.
+Assigns delegated notifications of the left-side dock.
 
 Create-only property.
 
 =item dockerDelegationsRight ARRAY
 
-Assigns the right-side dock list of delegated notifications.
+Assigns delegated notifications of the right-side dock.
 
 Create-only property.
 
 =item dockerDelegationsTop ARRAY
 
-Assigns the top-side dock list of delegated notifications.
+Assigns delegated notifications of the top-side dock.
 
 Create-only property.
 
 =item dockerDelegationsBottom ARRAY
 
-Assigns the bottom-side dock list of delegated notifications.
+Assigns delegated notifications of the bottom-side dock.
 
 Create-only property.
 
 =item dockerDelegationsClient ARRAY
 
-Assigns the center dock list of delegated notifications.
+Assigns delegated notifications of the bottom-side dock.
 
 Create-only property.
 
 =item dockerCommonProfile HASH
 
-Assigns hash of properties, passed to all five dock widgets during the creation.
+Assigns a hash of properties, passed to all the five dock widgets during the creation.
 
 Create-only property.
 
@@ -2262,15 +2247,17 @@ Create-only property.
 
 =head1 Prima::InternalDockerShuttle
 
-The class provides a container, or a 'shuttle', for a client widget, while is docked to
-an C<Prima::AbstractDocker::Interface> descendant instance. The functionality includes
-communicating with dock widgets, the user interface for dragging and interactive dock selection,
-and a client widget container for non-docked state. The latter is implemented by
-reparenting of the client widget to an external shuttle widget, selected by C<externalDockerClass>
-property. Both user interfaces for the docked and the non-docked shuttle states are minimal.
+The class provides a container, or a 'shuttle', for a client widget, while is
+docked to a C<Prima::AbstractDocker::Interface> descendant instance. The
+functionality includes communicating with dock widgets, the user interface for
+dragging and interactive dock selection, and a client widget container for the
+non-docked state. The latter is implemented by reparenting the client widget
+to an external shuttle widget, selected by the C<externalDockerClass> property.
+Both user interfaces for the docked and the non-docked shuttle states are
+minimal.
 
-The class implements dockable widget functionality, served by C<Prima::AbstractDocker::Interface>,
-while itself it is derived from C<Prima::Widget> only.
+The class implements dockable widget functionality, served by
+C<Prima::AbstractDocker::Interface>, and is derived from C<Prima::Widget>.
 
 See also: L</Prima::ExternalDockerShuttle>.
 
@@ -2281,7 +2268,7 @@ See also: L</Prima::ExternalDockerShuttle>.
 =item client WIDGET
 
 Provides access to the client widget, which always resides either in
-the internal or the external shuttle. By default there is no client,
+the internal or the external shuttle. By default, there is no client,
 and any widget capable of changing its parent can be set as one.
 After a widget is assigned as a client, its C<owner> and C<clipOwner>
 properties must not be used.
@@ -2297,7 +2284,7 @@ Default value: C<undef>
 
 =item dockingRoot WIDGET
 
-Selects the root of dock widgets hierarchy.
+Selects the root of the dock widgets hierarchy.
 If C<undef>, the shuttle can only exist in the non-docked state.
 
 Default value: C<undef>
@@ -2306,23 +2293,23 @@ See L</USAGE> for reference.
 
 =item externalDockerClass STRING
 
-Assigns class of external shuttle widget.
+Assigns the class of the external shuttle widget.
 
 Default value: C<Prima::ExternalDockerShuttle>
 
 =item externalDockerModule STRING
 
-Assigns module that contains the external shuttle widget class.
+Assigns the module that contains the external shuttle widget class.
 
 Default value: C<Prima::MDI> ( C<Prima::ExternalDockerShuttle> is derived from C<Prima::MDI> ).
 
 =item externalDockerProfile HASH
 
-Assigns hash of properties, passed to the external shuttle widget during the creation.
+Assigns a hash of properties, passed to the external shuttle widget during the creation.
 
 =item fingerprint INTEGER
 
-A custom bit mask, used to reject inappropriate dock widgets on early stage.
+A custom bit mask used to reject inappropriate dock widgets at an early stage.
 
 Default value: C<0x0000FFFF>
 
@@ -2335,10 +2322,10 @@ Default value: C<5,5,5,5>.
 
 =item snapDistance INTEGER
 
-A maximum offset, in pixels, between the actual shuttle coordinates and the coordinates
-proposed by the dock widget, where the shuttle is allowed to land.
-In other words, it is the distance between the dock and the shuttle when the latter
-'snaps' to the dock during the dragging session.
+A maximum offset, in pixels, between the actual shuttle coordinates and the
+coordinates proposed by the dock widget, where the shuttle is allowed to land.
+In other words, it is the distance between the dock and the shuttle when the
+latter 'snaps' to the dock during the dragging session.
 
 Default value: 10
 
@@ -2362,9 +2349,8 @@ Default value: 0
 
 =item client2frame X1, Y1, X2, Y2
 
-Returns a rectangle that the shuttle would occupy if
-its client rectangle is assigned to X1, Y1, X2, Y2
-rectangle.
+Returns the rectangle that the shuttle would occupy if its client rectangle is
+assigned to X1, Y1, X2, Y2 .
 
 =item dock_back
 
@@ -2372,53 +2358,50 @@ Docks to the recent dock widget, if it is still available.
 
 =item drag STATE, RECT, ANCHOR_X, ANCHOR_Y
 
-Initiates or aborts the dragging session, depending on STATE boolean
+Initiates or aborts the dragging session, depending on the STATE boolean
 flag.
 
 If it is 1, RECT is an array with the coordinates of the shuttle rectangle
-before the drag has started; ANCHOR_X and ANCHOR_Y are coordinates of the
-aperture point where the mouse event occurred that has initiated the drag.
+before the session has started; ANCHOR_X and ANCHOR_Y are coordinates of the
+aperture point where the mouse event occurred that has initiated the session.
 Depending on how the drag session ended, the shuttle can be relocated to
 another dock, undocked, or left intact. Also, C<Dock>, C<Undock>, or
 C<FailDock> notifications can be triggered.
 
-If STATE is 0, RECT, ANCHOR_X ,and ANCHOR_Y parameters are not used.
+If the STATE is 0, RECT, ANCHOR_X ,and ANCHOR_Y parameters are not used.
 
 =item find_docking DOCK, [ POSITION ]
 
-Opens a session with DOCK, unless it is already opened,
-and negotiates about the possibility of landing (
-at particular POSITION, if this parameter is present ).
+Opens a session with DOCK, unless it is already opened, and negotiates about
+the possibility of landing ( at the POSITION if this parameter is
+present ).
 
-C<find_docking> caches the dock widget sessions, and provides a
-possibility to select different parameters passed to C<open_session>
-for different dock widgets. To achieve this, C<GetCaps> request
-notification is triggered, which fills the parameters. The default
-action sets C<sizeable> options according to C<x_sizeable>
-and C<y_sizeable> properties.
+C<find_docking> caches the dock widget sessions and provides a possibility to
+select different parameters passed to C<open_session> for different dock
+widgets. To achieve this, the C<GetCaps> request notification is triggered,
+which is expected to fill the parameters. The default action sets the C<sizeable>
+option according to the C<x_sizeable> and C<y_sizeable> properties.
 
-In case an appropriate landing area is found, C<Landing>
+In case an appropriate landing area is found, the C<Landing>
 notification is triggered with the proposed dock widget
-and the target rectangle. The area can be rejected on this stage
-if C<Landing> returns negative answer.
+and the target rectangle. The area can be rejected at this stage
+if C<Landing> returns a negative answer.
 
 On success, returns a dock widget found and the target rectangle;
-the widget is never docked though. On failure returns an empty array.
+the widget is not docked though. On failure returns an empty array.
 
-This method is used by the dragging routine to provide a visual feedback to
-the user, to indicate that a shuttle may or may not land in a particular
-area.
+This method is used by the mouse dragging routine to provide visual feedback to
+the user, to indicate that a shuttle may or may not land in a particular area.
 
 =item frame2client X1, Y1, X2, Y2
 
-Returns a rectangle that the client would occupy if
-the shuttle rectangle is assigned to X1, Y1, X2, Y2
-rectangle.
+Returns the rectangle that the client would occupy if the shuttle rectangle is
+assigned to X1, Y1, X2, Y2 .
 
 =item redock
 
-If docked, undocks form the dock widget and docks back.
-If not docked, does not perform anything.
+Undocks from the dock widget and immediately tries to land back.
+If not docked, does not do anything.
 
 =back
 
@@ -2428,53 +2411,52 @@ If not docked, does not perform anything.
 
 =item Dock
 
-Called when shuttle is docked.
+Called when the shuttle was docked.
 
 =item EDSClose
 
-Triggered when the user presses close button or otherwise activates the
-C<close> function of the EDS ( external docker shuttle ). To cancel
-the closing, C<clear_event> must be called inside the event handler.
+Triggered when the user presses the close button or otherwise activates the
+C<close> function of the EDS ( external docker shuttle ) pseudo-window. To
+cancel the window closing C<clear_event> must be called inside the event handler.
 
 =item FailDock X, Y
 
-Called after the dragging session in the non-docked stage is finished,
+Called after the dragging session in the non-docked stage was finished
 but did not result in docking. X and Y are the coordinates
 of the new external shuttle position.
 
 =item GetCaps DOCK, PROFILE
 
-Called before the shuttle opens a docking session with DOCK
+Called before the shuttle opens a docking session with the DOCK
 widget. PROFILE is a hash reference, which is to be filled
 inside the event handler. After that PROFILE is passed
-to C<open_session> call.
+to an C<open_session> call.
 
-The default action sets C<sizeable> options according to C<x_sizeable>
+The default action sets the C<sizeable> option according to the C<x_sizeable>
 and C<y_sizeable> properties.
 
 =item Landing DOCK, X1, Y1, X2, Y2
 
-Called inside the docking session, after an appropriate dock
-widget is selected and the landing area is defined as
-X1, Y1, X2, Y2. To reject the landing on either DOCK or
-area, C<clear_event> must be called.
+Called inside the docking session, after an appropriate dock widget is selected
+and the landing area is defined as X1, Y1, X2, Y2. To reject the landing on
+either DOCK or area, C<clear_event> must be called.
 
 =item Undock
 
-Called when shuttle is switched to the non-docked state.
+Called when the shuttle is switched to the non-docked state.
 
 =back
 
 =head1 Prima::ExternalDockerShuttle
 
-A shuttle class, used to host a client of C<Prima::InternalDockerShuttle>
-widget when it is in the non-docked state. The class represents an
-emulation of a top-level window, which can be moved, resized ( this
-feature is not on by default though ), and closed.
+A shuttle class, hosts a client of the C<Prima::InternalDockerShuttle> widget when
+it is in the non-docked state. The widget is a pseudo-window with some minimal
+decorations that can be moved, resized ( this feature is not on by default
+though ), and closed.
 
-C<Prima::ExternalDockerShuttle> is inherited from C<Prima::MDI> class, and
-its window emulating functionality is a subset of its ascendant.
-See also L<Prima::MDI>.
+C<Prima::ExternalDockerShuttle> is inherited from the C<Prima::MDI> class, and
+its window-emulating functionality is a subset of its ascendant.  See also
+L<Prima::MDI>.
 
 =head2 Properties
 
@@ -2482,7 +2464,7 @@ See also L<Prima::MDI>.
 
 =item shuttle WIDGET
 
-Contains reference to the dockable WIDGET
+Contains the reference to the dockable WIDGET
 
 =back
 
@@ -2490,8 +2472,7 @@ Contains reference to the dockable WIDGET
 
 A simple descendant of C<Prima::InternalDockerShuttle>, used
 for toolbars. Introduces orientation and draws a tiny header along
-the minor shuttle axis. All its properties concern only
-the way the shuttle draws itself.
+the minor shuttle axis. 
 
 =head2 Properties
 
@@ -2499,14 +2480,14 @@ the way the shuttle draws itself.
 
 =item headerBreadth INTEGER
 
-Breadth of the header in pixels.
+The breadth of the header in pixels.
 
 Default value: 8
 
 =item indent INTEGER
 
-Provides a wrapper to C<indents> property; besides the
-space for the header, all indents are assigned to C<indent>
+A wrapper to the C<indents> property; besides the
+space for the header, all indents are assigned to the C<indent>
 property value.
 
 =item vertical BOOLEAN