From baf58fb02175d8481fece886e98e11dced4618aa Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=BCrg=20Lehni?= <juerg@scratchdisk.com>
Date: Thu, 21 Jul 2016 15:30:31 +0200
Subject: [PATCH] Improve documentation of PathItem#getArea() and
 PathItem#isClockwise()

---
 src/path/CompoundPath.js | 8 +++++---
 src/path/PathItem.js     | 7 ++++++-
 2 files changed, 11 insertions(+), 4 deletions(-)

diff --git a/src/path/CompoundPath.js b/src/path/CompoundPath.js
index 51b69571..89061102 100644
--- a/src/path/CompoundPath.js
+++ b/src/path/CompoundPath.js
@@ -240,8 +240,10 @@ var CompoundPath = PathItem.extend(/** @lends CompoundPath# */{
     },
 
     /**
-     * The area that the path's geometry is covering. Self-intersecting paths
-     * can contain sub-areas that cancel each other out.
+     * The area that the compound-path's geometry is covering, calculated by
+     * getting th e{@link Path#getArea()} of each sub-path and it adding up.
+     * Note that self-intersecting paths and sub-paths of different orientation
+     * can result in areas that cancel each other out.
      *
      * @bean
      * @type Number
@@ -256,7 +258,7 @@ var CompoundPath = PathItem.extend(/** @lends CompoundPath# */{
 
     /**
      * The total length of all sub-paths in this compound-path, calculated by
-     * getting {@link Path#getLength()} of each sub-path and it adding up.
+     * getting the {@link Path#getLength()} of each sub-path and it adding up.
      *
      * @bean
      * @type Number
diff --git a/src/path/PathItem.js b/src/path/PathItem.js
index e3a37113..d32f845a 100644
--- a/src/path/PathItem.js
+++ b/src/path/PathItem.js
@@ -91,10 +91,15 @@ var PathItem = Item.extend(/** @lends PathItem# */{
     },
 
     /**
-     * Specifies whether the path is oriented clock-wise.
+     * Specifies whether the path as a whole is oriented clock-wise, by looking
+     * at the path's area.
+     * Note that self-intersecting paths and sub-paths of different orientation
+     * can result in areas that cancel each other out.
      *
      * @bean
      * @type Boolean
+     * @see Path#getArea()
+     * @see CompoundPath#getArea()
      */
     isClockwise: function() {
         return this.getArea() >= 0;