Doxygen.

simgear/route/route.hxx

@@ -1,5 +1,8 @@
-// route.hxx -- Class to manage a list of waypoints (route)
+/**
-//
+ * \file route.hxx
+ * Provides a class to manage a list of waypoints (i.e. a route).
+ */
+
 // Written by Curtis Olson, started October 2000.
 //
 // Copyright (C) 2000  Curtis L. Olson  - curt@hfrl.umn.edu
@@ -44,6 +47,9 @@ SG_USING_STD(vector);
 
 #include <simgear/route/waypoint.hxx>
 
+/**
+ * A class to manage a list of waypoints (i.e. a route).
+ */
 
 class SGRoute {
 
@@ -55,16 +61,22 @@ private:
 
 public:
 
+    /** Constructor */
     SGRoute();
+
+    /** Destructor */
     ~SGRoute();
 
-    // clear the entire route
+    /** Clear the entire route */
     inline void clear() {
 	route.clear();
 	current_wp = 0;
     }
 
-    // add a waypoint
+    /**
+     * Add a waypoint.
+     * @param wp a waypoint
+     */
     inline void add_waypoint( const SGWayPoint &wp ) {
 	route.push_back( wp );
 
@@ -77,10 +89,16 @@ public:
 	}
     }
 
-    // get the number of waypoints
+    /**
+     * Get the number of waypoints (i.e. route length )
+     * @return route length
+     */
     inline int size() const { return route.size(); }
 
-    // get the front waypoint
+    /**
+     * Get the front waypoint.
+     * @return the first waypoint.
+     */
     inline SGWayPoint get_first() const {
 	if ( route.size() ) {
 	    return route[0];
@@ -89,7 +107,10 @@ public:
 	}
     }
 
-    // get the current waypoint
+    /**
+     * Get the current waypoint
+     * @return the current waypoint
+     */
     inline SGWayPoint get_current() const {
 	if ( current_wp < (int)route.size() ) {
 	    return route[current_wp];
@@ -98,21 +119,28 @@ public:
 	}
     }
 
-    // set the current waypoint
+    /**
+     * Set the current waypoint
+     * @param number of waypoint to make current.
+     */
     inline void set_current( int n ) {
 	if ( n >= 0 && n < (int)route.size() ) {
 	    current_wp = n;
 	}
     }
 
-    // increment the current waypoint
+    /** Increment the current waypoint pointer. */
     inline void increment_current() {
 	if ( current_wp < (int)route.size() - 1 ) {
 	    ++current_wp;
 	}
     }
 
-    // get the nth waypoint
+    /**
+     * Get the nth waypoint
+     * @param n waypoint number
+     * @return the nth waypoint
+     */
     inline SGWayPoint get_waypoint( const int n ) const {
 	if ( n < (int)route.size() ) {
 	    return route[n];
@@ -121,17 +149,19 @@ public:
 	}
     }
 
-    // delete the front waypoint
+    /** Delete the front waypoint */
     inline void delete_first() {
 	if ( route.size() ) {
 	    route.erase( route.begin() );
 	}
     }
 
-    // Calculate perpendicular distance from the current route segment
+    /**
-    // This routine assumes all points are laying on a flat plane and
+     * Calculate perpendicular distance from the current route segment
-    // ignores the altitude (or Z) dimension.  For best results, use
+     * This routine assumes all points are laying on a flat plane and
-    // with CARTESIAN way points.
+     * ignores the altitude (or Z) dimension.  For most accurate
+     * results, use with CARTESIAN way points.
+     */
     double distance_off_route( double x, double y ) const;
 };
 

simgear/route/waypoint.hxx

@@ -1,5 +1,8 @@
-// waypoint.hxx -- Class to hold data and return info relating to a waypoint
+/** 
-//
+ * \file waypoint.hxx
+ * Provides a class to manage waypoints
+ */
+
 // Written by Curtis Olson, started September 2000.
 //
 // Copyright (C) 2000  Curtis L. Olson  - curt@hfrl.umn.edu
@@ -41,10 +44,26 @@
 SG_USING_STD(string);
 
 
+/**
+ * A class to manage waypoints.
+ */
+
 class SGWayPoint {
 
 public:
 
+    /**
+     * Waypoint mode.
+     * <li> WGS84 requests all bearing and distance math be done assuming a
+     *      WGS84 ellipsoid world.  This is the most expensive computationally,
+     *      but also the most accurate.
+     * <li> SPHERICAL requests all bearing and distance math be done assuming
+     *      the world is a perfect sphere.  This is less compuntationally
+     *      expensive than using wgs84 math and still a fairly good
+     *      approximation of the real world, especially over shorter distances.
+     * <li> CARTESIAN requests all math be done assuming the coordinates specify
+     *      position in a Z = up world.
+     */
     enum modetype { 
 	WGS84 = 0,
 	SPHERICAL = 1,
@@ -64,32 +83,82 @@ private:
 
 public:
 
+    /** Default constructor */
     SGWayPoint();
+
+    /**
+     * Construct a waypoint
+     * @param lon destination longitude
+     * @param lat destination latitude
+     * @param alt target altitude
+     * @param mode type of coordinates/math to use
+     * @param s waypoint identifier
+     */
     SGWayPoint( const double lon, const double lat, const double alt,
 		const modetype m = WGS84, const string s = "" );
+
+    /** Destructor */
     ~SGWayPoint();
 
-    // Calculate course and distances.  For WGS84 and SPHERICAL
+    /**
-    // coordinates lat, lon, and course are in degrees, alt and
+     * Calculate course and distances.  For WGS84 and SPHERICAL
-    // distance are in meters.  For CARTESIAN coordinates x = lon, y =
+     * coordinates lat, lon, and course are in degrees, alt and
-    // lat.  Course is in degrees and distance is in what ever units x
+     * distance are in meters.  For CARTESIAN coordinates x = lon, y =
-    // and y are in.
+     * lat.  Course is in degrees and distance is in what ever units x
+     * and y are in.
+     * @param cur_lon (in) current longitude
+     * @param cur_lat (in) current latitude
+     * @param cur_alt (in) current altitude
+     * @param course (out) heading from current location to this waypoint
+     * @param distance (out) distance from current location to this waypoint
+     */
     void CourseAndDistance( const double cur_lon, const double cur_lat,
 			    const double cur_alt,
 			    double *course, double *distance ) const;
 
-    // Calculate course and distances between two waypoints
+    /**
+     * Calculate course and distances between a specified starting waypoint
+     * and this waypoint.
+     * @param wp (in) original waypoint
+     * @param course (out) heading from current location to this waypoint
+     * @param distance (out) distance from current location to this waypoint
+     */
     void CourseAndDistance( const SGWayPoint &wp,
 			    double *course, double *distance ) const;
 
+    /** @return waypoint mode */
     inline modetype get_mode() const { return mode; }
+
+    /** @return waypoint longitude */
     inline double get_target_lon() const { return target_lon; }
+
+    /** @return waypoint latitude */
     inline double get_target_lat() const { return target_lat; }
+
+    /** @return waypoint altitude */
     inline double get_target_alt() const { return target_alt; }
+
+    /**
+     * This value is not calculated by this class.  It is simply a
+     * placeholder for the user to stash a distance value.  This is useful
+     * when you stack waypoints together into a route.  You can calculate the
+     * distance from the previous waypoint once and save it here.  Adding up
+     * all the distances here plus the distance to the first waypoint gives you
+     * the total route length.  Note, you must update this value yourself, this
+     * is for your convenience only.
+     * @return waypoint distance holder (what ever the user has stashed here)
+     */
     inline double get_distance() const { return distance; }
+
+    /**
+     * Set the waypoint distance value to a value of our choice.
+     * @param d distance 
+     */
+    inline void set_distance( double d ) { distance = d; }
+
+    /** @return waypoint id */
     inline string get_id() const { return id; }
 
-    inline void set_distance( double d ) { distance = d; }
 };