glide_computer example documentation updated

docs/examples/glide_computer.rst

@@ -1,7 +1,55 @@
 glide_computer
 ==============
 
+This example presents the usage of:
+
+- different units for length, time, and velocity,
+- quantities text output formatting,
+- `quantity_point` to mark "absolute" values like ``altitude`` (as opposed to ``height``),
+- a simple ``vector`` class to show how to handle 3D space for aviation needs and how to build abstractions
+  on top of a `Quantity` concept.
+
+``vector`` class template provides a strong type that divides quantities and quantity points to the ones
+on a horizontal (X, Y) plane and vertical (Z) axis. Its purpose is to make different kinds of quantity
+(i.e. length) separated strong types (i.e. distance, height). Additionally, it wraps both a `quantity`
+and `quantity_point` types which means that we can define a ``height`` and ``altitude`` respectively
+as different strong types. Some of its function are defined only for quantities (additional operators)
+and some for quantity points (additional constructor).
+
 .. literalinclude:: ../../example/glide_computer.cpp
-  :caption: glide_computer.cpp
+  :caption: 3D ``vector`` definition
   :start-at: #include
+  :end-before: // custom types
   :linenos:
+  :lineno-match:
+
+The next part of the example defines strong types used by the glide calculator engine. For example
+we have 3 :term:`kinds of quantities <kind>` for a quantity of length:
+
+- ``distance`` - a relative horizontal distance between 2 points on Earth
+- ``height`` - a relative altitude difference between 2 points in the air
+- ``altitude`` - an absolute altitude value measured form the mean sea level (AMSL).
+
+For the last case a custom text output is provided both for C++ output streams and the text formatting
+facility.
+
+.. literalinclude:: ../../example/glide_computer.cpp
+  :caption: Strong types for different kind of quantities
+  :start-at: // custom types
+  :end-before: // An example of a really
+  :linenos:
+  :lineno-match:
+
+The engine of this simple glide computer works on quantities of the SI units with a floating-point
+representation. The user can pass any unit valid for a given quantity and the library will automatically
+convert it to the one required by the engine interface.
+
+The glide calculator estimates the number of flight phases (towing, circling, gliding, final glide) needed
+to finish a task and the duration needed to finish it while flying a selected glider in the specific weather
+conditions.
+
+.. literalinclude:: ../../example/glide_computer.cpp
+  :caption: Glide computer implementation
+  :start-at: // An example of a really simplified tactical glide computer
+  :linenos:
+  :lineno-match:

example/glide_computer.cpp

@@ -28,21 +28,6 @@
 #include <array>
 #include <iostream>
 
-// An example of a really simplified tactical glide computer
-// Simplifications:
-// - glider 100% clean and with full factory performance (brand new painting)
-// - no influence of the ballast (pilot weight, water, etc) to glider performance
-// - only one point on a glider polar curve
-// - no influence of bank angle (during circling) on a glider performance
-// - no wind
-// - constant thermals strength
-// - thermals exactly where and when we need them ;-)
-// - no airspaces
-// - Earth is flat
-// - ground level changes linearly between airports
-// - no ground obstacles (i.e. mountains) to pass
-// - flight path exactly on a shortest possible line to destination
-
 // horizontal/vertical vector
 namespace {
 
@@ -245,6 +230,21 @@ struct fmt::formatter<altitude> : formatter<si::length<si::metre>> {
   }
 };
 
+// An example of a really simplified tactical glide computer
+// Simplifications:
+// - glider 100% clean and with full factory performance (brand new painting)
+// - no influence of the ballast (pilot weight, water, etc) to glider performance
+// - only one point on a glider polar curve
+// - no influence of bank angle (during circling) on a glider performance
+// - no wind
+// - constant thermals strength
+// - thermals exactly where and when we need them ;-)
+// - no airspaces
+// - Earth is flat
+// - ground level changes linearly between airports
+// - no ground obstacles (i.e. mountains) to pass
+// - flight path exactly on a shortest possible line to destination
+
 // gliders database
 namespace {