From: Wolfgang Bangerth Date: Tue, 17 Oct 2017 03:59:39 +0000 (-0600) Subject: Better explain the meaning of Point. X-Git-Tag: v9.0.0-rc1~940^2 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F5254%2Fhead;p=dealii.git Better explain the meaning of Point. --- diff --git a/include/deal.II/base/point.h b/include/deal.II/base/point.h index 103582dbde..2b63fd5c4d 100644 --- a/include/deal.II/base/point.h +++ b/include/deal.II/base/point.h @@ -25,16 +25,31 @@ DEAL_II_NAMESPACE_OPEN /** - * A class that represents a point in a space with arbitrary dimension - * dim. + * A class that represents a point in a Cartesian space of dimension + * @p dim . * - * Objects of this class are used to represent points, i.e., vectors anchored - * at the origin of a Cartesian vector space. They are, among other uses, - * passed to functions that operate on points in spaces of a priori fixed - * dimension: rather than using functions like double f(double x) and - * double f(double x, double y), you should use double - * f(Point &p) instead as it allows writing dimension independent - * code. + * Objects of this class are used to represent points (i.e., vectors + * anchored at the origin) of a vector space equipped with a Cartesian + * coordinate system. They are, among other uses, passed to + * functions that operate on points in spaces of a priori fixed + * dimension: rather than using functions like double f(const + * double x) and double f(const double x, const double + * y), you can use double f(const Point &p) + * instead as it allows writing dimension independent code. + * + * deal.II specifically uses Point objects as indicating points that + * are represented by Cartesian coordinates, i.e., where a point in @p + * dim space dimensions is characterized by signed distances along the + * axes of a coordinate system spanned by @p dim mutually orthogonal + * unit vectors (called the "coordinate axes"). This choice of + * representing a vector makes addition and scaling of vectors + * particularly simple: one only has to add or multiply each + * coordinate value. On the other hand, adding or scaling vectors is + * not nearly as simple when a vector is represented in other kinds of + * coordinate systems (e.g., spherical + * coordinate systems). * * *

What's a Point@ and what is a