As written the class comments (i.e. the public documentation) for the
Area class do little to explain the unique properties of this class
and how it differs from other implementations of the Shape interface.

The tendency seems to be to equate this class with being a "fancier
GeneralPath" with some very powerful extended methods, but the real
purpose of the Area class is to provide powerful CAG (Constructive
Area Geometry) operations on enclosed areas.

To that end, whereas GeneralPath can store arbitrary shapes which
may be closed or open and which may have spurious degenerate sub-shapes,
the Area class only stores a collection of non-empty, non-overlapping
closed sub-shapes. Part of the construction of an Area object from
a Shape is to analyze the shape and form an alternate representation
which has the following properties:

- All sub-paths of the outline are closed paths

- All sub-paths enclose a non-empty area

- None of the sub-paths intersect with themselves
or any of the other sub-paths in the same Area
object (though the outlines may touch as long as
they do not cross).

- The geometry of the outline of each subpath resembles
the geometry of the original Shape only in that it
encloses the same area but may use entirely different
types and ordering of the segments to do so.

Particular problems that have arisen in the past which have confused
users are as follows:

- Creating an area from an unclosed (open) Shape
results in a closed outline in the Area object

- Creating an area from a Shape which encloses no
area (even when "closed") produces an empty Area.
The most common example is that an Area produced
from a line will be empty since the line encloses
no area.

- A self-intersecting shape may be split into two
shapes representing each non-intersecting half
of the original.

- The Area may take more path segments to describe
the same geometry even when the original outline
is simple and obvious. (The analysis that the
Area object must perform on the path may not
recognize the same rules of "simple and obvious"
as a human being.)