Update docstrings according to jklymak

Apply suggestions from @jklymak code review

Co-authored-by: Jody Klymak <[email protected]>

Author: deep-jkl

doc/users/next_whats_new/extending_MarkerStyle.rst

@@ -1,9 +1,8 @@
 New customization of MarkerStyle
 --------------------------------
 
-New MarkerStyle parameters allow control of join style and cap style. 
-The appearance of individual markers can be further controlled by 
-transform supplied during creation.
+New MarkerStyle parameters allow control of join style and cap style, and for
+the user to supply a transformation to be applied to the marker (e.g. a rotation).
 
 .. plot::
     :include-source: true

examples/lines_bars_and_markers/marker_reference.py

@@ -166,10 +166,8 @@ def split_list(a_list):
 # Advanced marker modifications with transform
 # ============================================
 #
-# All markers can be modified by a user transform in MarkerStyle constructor.
-# Supplied transform is combined with the default transforms needed for
-# selected marker shape (e.g. caret up, caret down). Following example shows
-# how user supplied rotation applies to several marker shapes.
+# Markers can be modified by passing a transform to the MarkerStyle constructor.
+# Following example shows how a supplied rotation is applied to several marker shapes.
 
 common_style = {k: v for k, v in filled_marker_style.items() if k != 'marker'}
 angles = [0, 10, 20, 30, 45, 60, 90]
@@ -204,9 +202,8 @@ def split_list(a_list):
 # Setting marker cap style and join style
 # =======================================
 #
-# All markers have predefined cap style and join style, but this can be
-# overriden during creation of MarkerStyle. Follwing example show how to
-# change the cap style and how different styles look.
+# Markers have default cap and join styles, but these can be
+# customized when creating a MarkerStyle.
 
 from matplotlib.markers import JoinStyle, CapStyle
 
@@ -240,8 +237,7 @@ def split_list(a_list):
 plt.show()
 
 ###############################################################################
-# Follwing example show how to change the join style and how different styles
-# looks like.
+# Modifying the join style:
 
 fig, ax = plt.subplots()
 fig.suptitle('Marker JoinStyle', fontsize=14)

examples/lines_bars_and_markers/multivariate_marker_plot.py

@@ -4,10 +4,9 @@
 ==============================================
 
 This example shows how to use different properties of markers to plot
-multivariate datasets. Following example shows an illustrative case of
-plotting success of baseball throw as an smiley face with size mapped to
-the skill of thrower, rotation mapped to the take-off angle, and thrust
-to the color of the marker.
+multivariate datasets. Here we represent a successful baseball throw as a smiley 
+face with marker size mapped to the skill of thrower, marker rotation to the take-off angle, 
+and thrust to the marker color.
 """
 
 import numpy as np

lib/matplotlib/markers.py

@@ -82,13 +82,9 @@
     plt.plot([1, 2, 3], marker=11)
     plt.plot([1, 2, 3], marker=matplotlib.markers.CARETDOWNBASE)
 
-Markers have some reasonable default settings for join and cap styles.
-However, those can be overriden when creating a new instance of MarkerStyle.
-Furthermore, the marker shape can be modified by supplying
-`~matplotlib.transforms.Transform` during creation.
-Some markers are created as internally rotated shapes (e.g. triangles).
-For such cases, both internal and user supplied transforms are combined.
-
+Markers join and cap styles can be customized by creating a new instance of MarkerStyle.
+A MarkerStyle can also have a custom
+`~matplotlib.transforms.Transform` allowing it to be arbitrarily rotated or offset.  
 Examples showing the use of markers:
 
 * :doc:`/gallery/lines_bars_and_markers/marker_reference`
@@ -253,16 +249,13 @@ def __init__(self, marker=_unset, fillstyle=None,
             One of 'full', 'left', 'right', 'bottom', 'top', 'none'.
 
         transform : Affine2D, default: None
-            User supplied transformation that will be combined with the
-            native transformation of selected marker.
+            Transform that will be combined with the native transform of the marker.
 
         capstyle : CapStyle, default: None
-            User supplied cap style that will override the default cap
-            style of selected marker.
+            Cap style that will override the default cap style of the marker.
 
         joinstyle : JoinStyle, default: None
-            User supplied join style that will override the default cap
-            style of selected marker.
+            Join style that will override the default join style of the marker.
         """
         self._marker_function = None
         self._user_transform = transform
@@ -431,7 +424,7 @@ def get_user_transform(self):
 
     def transformed(self, transform: Affine2D):
         """
-        Return new marker with combined transformation.
+        Return a new version of this marker with the transform applied. 
 
         Parameters
         ----------
@@ -447,15 +440,15 @@ def transformed(self, transform: Affine2D):
 
     def rotated(self, deg=None, rad=None):
         """
-        Return new marker rotated by specified angle.
+        Return a new version of this marker rotated by specified angle.
 
         Parameters
         ----------
         deg : float, default: None
-            Use this parameter to specify rotation angle in degrees.
+            Rotation angle in degrees.
 
         rad : float, default: None
-            Use this parameter to specify rotation angle in radians.
+            Rotation angle in radians.
 
         .. note:: You must specify exactly one of deg or rad.
         """