doxygen ...

simgear/bucket/newbucket.hxx

@@ -193,6 +193,7 @@ public:
      *
      * 3 bits - to represent x (0 to 7)
      * 3 bits - to represent y (0 to 7)
+     * @return tile index
      */
     inline long int gen_index() const {
 	return ((lon + 180) << 14) + ((lat + 90) << 6) + (y << 3) + x;
@@ -201,6 +202,7 @@ public:
     /**
      * Generate the unique scenery tile index for this bucket in ascii
      * string form.
+     * @return tile index in string form
      */
     inline string gen_index_str() const {
 	char tmp[20];
@@ -211,11 +213,12 @@ public:
 
     /**
      * Build the base path name for this bucket.
+     * @return base path in string form
      */
     string gen_base_path() const;
 
     /**
-     * Return the center lon of a tile.
+     * @return the center lon of a tile.
      */
     inline double get_center_lon() const {
 	double span = sg_bucket_span( lat + y / 8.0 + SG_HALF_BUCKET_SPAN );
@@ -228,51 +231,51 @@ public:
     }
 
     /**
-     * Return the center lat of a tile.
+     * @return the center lat of a tile.
      */
     inline double get_center_lat() const {
 	return lat + y / 8.0 + SG_HALF_BUCKET_SPAN;
     }
 
     /**
-     * Return width of the tile in degrees.
+     * @return the width of the tile in degrees.
      */
     double get_width() const;
 
     /**
-     * Return height of the tile in degrees.
+     * @return the height of the tile in degrees.
      */
     double get_height() const;
 
     /**
-     * Return width of the tile in meters.
+     * @return the width of the tile in meters.
      */
     double get_width_m() const; 
 
     /**
-     * Return height of the tile in meters.
+     * @return the height of the tile in meters.
      */
     double get_height_m() const;
  
     // Informational methods.
 
     /**
-     * Return the lon of the lower left corner of this tile.
+     * @return the lon of the lower left corner of this tile.
      */
     inline int get_lon() const { return lon; }
 
     /**
-     * Return the lat of the lower left corner of this tile.
+     * @return the lat of the lower left corner of this tile.
      */
     inline int get_lat() const { return lat; }
 
     /**
-     * Return the x coord within the 1x1 degree chunk this tile.
+     * @return the x coord within the 1x1 degree chunk this tile.
      */
     inline int get_x() const { return x; }
 
     /**
-     * Return the y coord within the 1x1 degree chunk this tile.
+     * @return the y coord within the 1x1 degree chunk this tile.
      */
     inline int get_y() const { return y; }
 
@@ -284,17 +287,20 @@ public:
 
 
 /**
+ * \relates SGBucket
  * Return the bucket which is offset from the specified dlon, dlat by
  * the specified tile units in the X & Y direction.
  * @param dlon starting lon in degrees
  * @param dlat starting lat in degrees
  * @param x number of bucket units to offset in x (lon) direction
  * @param y number of bucket units to offset in y (lat) direction
+ * @return offset bucket
  */
 SGBucket sgBucketOffset( double dlon, double dlat, int x, int y );
 
 
 /**
+ * \relates SGBucket
  * Calculate the offset between two buckets (in quantity of buckets).
  * @param b1 bucket 1
  * @param b2 bucket 2
@@ -320,6 +326,7 @@ operator<< ( ostream& out, const SGBucket& b )
  * Compare two bucket structures for equality.
  * @param b1 bucket 1
  * @param b2 bucket 2
+ * @return comparison result
  */
 inline bool
 operator== ( const SGBucket& b1, const SGBucket& b2 )

simgear/debug/logstream.hxx

@@ -86,10 +86,13 @@ public:
     // logbuf( streambuf* sb ) : sbuf(sb) {}
     /** Constructor */
     logbuf();
+
     /** Destructor */
     ~logbuf();
 
-    /** Is logging enabled? */
+    /**
+     * Is logging enabled?
+     * @return true or false*/
     bool enabled() { return logging_enabled; }
 
     /**
@@ -230,9 +233,11 @@ logstream::operator<< ( const loglevel& l )
 
 
 /**
+ * \relates logstream
  * Return the one and only logstream instance.
  * We use a function instead of a global object so we are assured that cerr
  * has been initialised.
+ * @return current logstream
  */
 inline logstream&
 sglog()

simgear/ephemeris/ephemeris.hxx

@@ -118,38 +118,38 @@ public:
     void update(double mjd, double lst, double lat);
 
     /**
-     * Returns a pointer to a Star class containing all the positional
+     * @return a pointer to a Star class containing all the positional
      * information for Earth's Sun.
      */
     inline Star *get_sun() const { return our_sun; }
 
-    /** Returns the right ascension of the Sun. */
+    /** @return the right ascension of the Sun. */
     inline double getSunRightAscension() const {
 	return our_sun->getRightAscension();
     }
 
-    /** Returns the declination of the Sun. */
+    /** @return the declination of the Sun. */
     inline double getSunDeclination() const {
 	return our_sun->getDeclination();
     }
 
     /**
-     * Returns a pointer to a Moon class containing all the positional
+     * @return a pointer to a Moon class containing all the positional
      * information for Earth's Moon.
      */
     inline MoonPos *get_moon() const { return moon; }
 
-    /** Returns the right ascension of the Moon. */
+    /** @return the right ascension of the Moon. */
     inline double getMoonRightAscension() const {
 	return moon->getRightAscension();
     }
 
-    /** Returns the declination of the Moon. */
+    /** @return the declination of the Moon. */
     inline double getMoonDeclination() const {
 	return moon->getDeclination();
     }
 
-    /** Returns the numbers of defined planets. */
+    /** @return the numbers of defined planets. */
     inline int getNumPlanets() const { return nplanets; }
 
     /**
@@ -158,10 +158,11 @@ public:
      * the ``sg'' package.) An sgdVec3 is a 3 element double
      * array. The first element is the right ascension of the planet,
      * the second is the declination, and the third is the magnitude.
+     * @return planets array
      */
     inline sgdVec3 *getPlanets() { return planets; }
 
-    /** Returns the numbers of defined stars. */
+    /** @return the numbers of defined stars. */
     inline int getNumStars() const { return stars->getNumStars(); }
 
     /**
@@ -169,6 +170,7 @@ public:
      * format. An The first element of the sgdVec3 is the right
      * ascension of the planet, the second is the declination, and the
      * third is the magnitude.
+     * @returns star array
      */
     inline sgdVec3 *getStars() { return stars->getStars(); }
 };

simgear/io/iochannel.hxx

@@ -96,6 +96,7 @@ public:
      *  - SG_IO_BI - data will be flowing in both directions. 
      *  - SG_IO_NONE - data will not be flowing in either direction.
      *                 This is here for the sake of completeness. 
+     * @return result of open
      */
     virtual bool open( const SGProtocolDir d );
 
@@ -109,6 +110,7 @@ public:
      * accomodate your input message
      * @param buf a char pointer to your input buffer 
      * @param length max number of bytes to read
+     * @return number of bytes read
      */
     virtual int read( char *buf, int length );
 
@@ -117,6 +119,7 @@ public:
      * stop at the first end of line encountered in the input buffer.
      * @param buf a char pointer to your input buffer 
      * @param length max number of bytes to read
+     * @return number of bytes read
      */
     virtual int readline( char *buf, int length );
 
@@ -128,6 +131,7 @@ public:
      * written out. The number of bytes written is returned.
      * @param buf a char pointer to your output buffer 
      * @param length number of bytes to write
+     * @return number of bytes written
      */
     virtual int write( const char *buf, const int length );
 
@@ -136,6 +140,7 @@ public:
      * calculate the length of a null terminated character array and
      * write it to the output channel.
      * @param buf a char pointer to your output buffer 
+     * @return number of bytes written
      */
     virtual int writestring( const char *str );
 
@@ -143,6 +148,7 @@ public:
      * The close() method is modeled after the close() Unix system
      * call and will close an open device. You should call this method
      * when you are done using your IO class, before it is destructed.
+     * @return result of close
      */
     virtual bool close();
 

simgear/io/sg_binobj.hxx

@@ -1,5 +1,8 @@
-// sg_binobj.hxx -- routines to read and write low level flightgear 3d objects
+/**
-//
+ * \file sg_binobj.hxx
+ * Routines to read and write the low level (binary) simgear 3d object format.
+ */
+
 // Written by Curtis Olson, started January 2000.
 //
 // Copyright (C) 2000  Curtis L. Olson  - curt@flightgear.org
@@ -19,7 +22,6 @@
 // Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 //
 // $Id$
-//
 
 
 #ifndef _SG_BINOBJ_HXX
@@ -45,33 +47,49 @@
 
 
 
+/** STL Structure used to store object information */
 typedef vector < int_list > group_list;
 typedef group_list::iterator group_list_iterator;
 typedef group_list::const_iterator const_group_list_iterator;
 
 
+/** Magic Number for our file format */
 #define SG_FILE_MAGIC_NUMBER  ( ('S'<<24) + ('G'<<16) + SG_BINOBJ_VERSION )
 
 
-/*
+/**
-   scenery-file: magic, nobjects, object+
+ * A class to manipulate the simgear 3d object format.
-   magic: "TG" + version
+ * This class provides functionality to both read and write the binary format.
-   object: obj_typecode, nproperties, nelements, property+, element+
+ *
-   element: nbytes, BYTE+
+ * Here is a really quick overview of the file syntax:
-   property: prop_typecode, nbytes, BYTE+
+ *
-   obj_typecode: bounding sphere | vertices | normals | texcoords | triangles |
+ * - scenery-file: magic, nobjects, object+
-                fans | strips 
+ *
-   prop_typecode: material_name | ???
+ * - magic: "TG" + version
-   nelements: SHORT (Gives us 65536 which ought to be enough, right?)
+ *
-   nproperties: SHORT
+ * - object: obj_typecode, nproperties, nelements, property+, element+
-   *_typecode: CHAR
+ *
-   nbytes: INTEGER (If we used short here that would mean 65536 bytes = 16384
+ * - element: nbytes, BYTE+
-                    floats = 5461 vertices which is not enough for future
+ *
-		    growth)
+ * - property: prop_typecode, nbytes, BYTE+
-   vertex: FLOAT, FLOAT, FLOAT
+ *
+ * - obj_typecode: bounding sphere | vertices | normals | texcoords |
+ *                 triangles | fans | strips 
+ *
+ * - prop_typecode: material_name | ???
+ *
+ * - nelements: SHORT (Gives us 65536 which ought to be enough, right?)
+ *
+ * - nproperties: SHORT
+ *
+ * - *_typecode: CHAR
+ *
+ * - nbytes: INTEGER (If we used short here that would mean 65536 bytes = 16384
+ *                    floats = 5461 vertices which is not enough for future
+ *	              growth)
+ *
+ * - vertex: FLOAT, FLOAT, FLOAT
 */
-
-
 class SGBinObject {
     Point3D gbs_center;
     float gbs_radius;
@@ -126,24 +144,46 @@ public:
     inline string_list get_fan_materials() const { return fan_materials; }
     inline void set_fan_materials( string_list s ) { fan_materials = s; }
 
-    // read a binary file object and populate the provided structures.
+    /**
+     * Read a binary file object and populate the provided structures.
+     * @param file input file name
+     * @return result of read
+     */
     bool read_bin( const string& file );
 
-    // write out the structures to a binary file.  We assume that the
+    /** 
-    // groups come to us sorted by material property.  If not, things
+     * Write out the structures to a binary file.  We assume that the
-    // don't break, but the result won't be as optimal.
+     * groups come to us sorted by material property.  If not, things
+     * don't break, but the result won't be as optimal.
+     * @param base name of output path
+     * @param name name of output file
+     * @param b bucket for object location
+     * @return result of write
+     */
     bool write_bin( const string& base, const string& name, const SGBucket& b );
 
-    // write out the structures to an ASCII file.  We assume that the
+    /**
-    // groups come to us sorted by material property.  If not, things
+     * Write out the structures to an ASCII file.  We assume that the
-    // don't break, but the result won't be as optimal.
+     * groups come to us sorted by material property.  If not, things
+     * don't break, but the result won't be as optimal.
+     * @param base name of output path
+     * @param name name of output file
+     * @param b bucket for object location
+     * @return result of write
+     */
     bool write_ascii( const string& base, const string& name,
 		      const SGBucket& b );
 };
 
 
-// calculate the bounding sphere.  Center is the center of the
+/**
-// tile and zero elevation
+ * \relates SGBinObject
+ * Calculate the bounding sphere of a set of nodes.
+ * Center is the center of the tile and zero elevation.
+ * @param center center of our bounding radius
+ * @param wgs84_nodes list of points in wgs84 coordinates
+ * @return radius
+ */
 double sgCalcBoundingRadius( Point3D center, point_list& wgs84_nodes );
 
 

simgear/io/sg_file.hxx

@@ -87,7 +87,7 @@ public:
     // close file
     bool close();
 
-    /** Return the name of the file being manipulated. */
+    /** @return the name of the file being manipulated. */
     inline string get_file_name() const { return file_name; }
 };
 

simgear/io/sg_serial.hxx

@@ -97,10 +97,10 @@ public:
     // close port
     bool close();
 
-    /** Return the serial port device name */
+    /** @return the serial port device name */
     inline string get_device() const { return device; }
 
-    /** Return the baud rate */
+    /** @return the baud rate */
     inline string get_baud() const { return baud; }
 };
 

simgear/io/sg_socket.hxx

@@ -167,13 +167,16 @@ public:
     // close file
     bool close();
 
-    /** Enable non-blocking mode. */
+    /**
+     * Enable non-blocking mode.
+     * @return success/failure
+     */
     bool nonblock();
 
-    /** Return the remote host name */
+    /** @return the remote host name */
     inline string get_hostname() const { return hostname; }
 
-    /** Return the port number (in string form) */
+    /** @return the port number (in string form) */
     inline string get_port_str() const { return port_str; }
 };
 

simgear/magvar/magvar.hxx

@@ -1,5 +1,8 @@
-// magvar.hxx -- magnetic variation wrapper class
+/** 
-//
+ * \file magvar.hxx
+ * Magnetic variation wrapper class.
+ */
+
 // Written by Curtis Olson, started July 2000.
 //
 // Copyright (C) 2000  Curtis L. Olson  - curt@flightgear.org
@@ -34,7 +37,21 @@
 #  include <config.h>
 #endif
 
-
+/**
+ * Magnetic variation wrapper class.
+ *
+ * The SGMagVar class calculates the magnetic variation and dip for
+ * any position, altitude, and time. It is a complete
+ * re-implimentation of the NIMA WMM 2000 (not derived from their demo
+ * code.)
+ *
+ * The SGMagVar class is really a simple wrapper around the core Ed
+ * Williams code which does all the hard work.  This class allows you
+ * to crunch the math once and then do multiple polls of the
+ * data. However, if your position, altitude, or time has changed
+ * significantly, you should call the update() method to recrunch new
+ * numbers.
+ */
 class SGMagVar {
 
 private:
@@ -44,19 +61,42 @@ private:
 
 public:
 
+    /**
+     * This creates an instance of the SGMagVar object.
+     * You must call the update() method before any queries will be valid.
+     */
     SGMagVar();
+
+    /** Destructor */
     ~SGMagVar();
 
-    // recalculate the magnetic offset and dip
+    /** Recalculate the magnetic offset and dip.
+     * The update() method requires you to pass in your position and
+     * the julian date. Lon and lat are specified in radians, altitude
+     * is specified in meters. Julian date can be conveniently
+     * calculated by using an instance of the SGTime class.
+     * @param lon longitude in radians
+     * @param lat latitude in radians
+     * @param alt_m altitude above sea level in meters
+     * @param jd julian date
+     */
     void update( double lon, double lat, double alt_m, double jd );
 
+    /** @return the current magnetic variation in radians. */
     double get_magvar() const { return magvar; }
+
+    /** @return the current magnetic dip in radians. */
     double get_magdip() const { return magdip; }
 };
 
 
-// lookup the magvar for any arbitrary location (doesn't save state
+/**
-// and note that this is a fair amount of cpu work)
+ * \relates SGMagVar
+ * Lookup the magvar for any arbitrary location (This function doesn't
+ * save state like the SGMagVar class.  This function triggers a fair
+ * amount of CPU work, so use it cautiously.
+ * @return the magvar in radians
+ */
 double sgGetMagVar( double lon, double lat, double alt_m, double jd );
 
 

simgear/math/Makefile.am

@@ -9,13 +9,13 @@ endif
 lib_LIBRARIES = libsgmath.a
 
 include_HEADERS = \
-	fg_memory.h \
 	interpolater.hxx \
 	leastsqs.hxx \
 	localconsts.hxx \
 	point3d.hxx \
 	polar3d.hxx \
 	sg_geodesy.hxx \
+	sg_memory.h \
 	sg_random.h \
 	sg_types.hxx \
 	vector.hxx

simgear/math/interpolater.cxx

@@ -106,7 +106,7 @@ double SGInterpTable::interpolate(double x) {
 
 
 // Destructor
-SGInterpTable::~SGInterpTable( void ) {
+SGInterpTable::~SGInterpTable() {
 }
 
 

simgear/math/interpolater.hxx

@@ -1,7 +1,9 @@
-//
+/**
-// interpolater.hxx -- routines to handle linear interpolation from a table of
+ * \file interpolater.hxx
-//                     x,y   The table must be sorted by "x" in ascending order
+ * Routines to handle linear interpolation from a table of x,y The
-//
+ * table must be sorted by "x" in ascending order
+ */
+
 // Written by Curtis Olson, started April 1998.
 //
 // Copyright (C) 1998  Curtis L. Olson  - curt@me.umn.edu
@@ -39,22 +41,33 @@ SG_USING_STD(string);
 
 #define MAX_TABLE_SIZE 32
 
-
+/**
+ * A class that provids a simple linear 2d interpolation lookup table.
+ * The actual table is expected to be loaded from a file.  The
+ * independant variable must be strictly ascending.  The dependent
+ * variable can be anything.
+ */
 class SGInterpTable {
     int size;
     double table[MAX_TABLE_SIZE][2];
 
 public:
 
-    // Constructor -- loads the interpolation table from the specified
+    /**
-    // file
+     * Constructor. Loads the interpolation table from the specified file.
+     * @param file name of interpolation file
+     */
     SGInterpTable( const string& file );
 
-    // Given an x value, linearly interpolate the y value from the table
+    /**
+     * Given an x value, linearly interpolate the y value from the table.
+     * @param x independent variable
+     * @return interpolated dependent variable
+     */
     double interpolate(double x);
 
-    // Destructor
+    /** Destructor */
-    ~SGInterpTable( void );
+    ~SGInterpTable();
 };
 
 

simgear/math/leastsqs.hxx

@@ -1,5 +1,8 @@
-// leastsqs.h -- Implements a simple linear least squares best fit routine
+/**
-//
+ * \file leastsqs.hxx
+ * Implements a simple linear least squares best fit routine.
+ */
+
 // Written by Curtis Olson, started September 1997.
 //
 // Copyright (C) 1997  Curtis L. Olson  - curt@infoplane.com
@@ -20,7 +23,6 @@
 // Boston, MA  02111-1307, USA.
 //
 // $Id$
-///
 
 
 #ifndef _LEASTSQS_H
@@ -32,39 +34,47 @@
 #endif                                   
 
 
-/* 
+/**
-Least squares fit:
+Classical least squares fit:
 
-y = b0 + b1x
+\f[
+    y = b_0 + b_1 * x
+\f]
 
-     n*sum(xi*yi) - (sum(xi)*sum(yi))
+\f[
-b1 = --------------------------------
+    b_1 = \frac{n * \sum_0^i (x_i*y_i) - \sum_0^i x_i* \sum_0^i y_i}
-     n*sum(xi^2) - (sum(xi))^2
+          {n*\sum_0^i x_i^2 - (\sum_0^i x_i)^2}
+\f]
 
-
+\f[
-b0 = sum(yi)/n - b1*(sum(xi)/n)
+    b_0 = \frac{\sum_0^i y_i}{n} - b_1 * \frac{\sum_0^i x_i}{n}
+\f]
 */
-
 void least_squares(double *x, double *y, int n, double *m, double *b);
 
-/* incrimentally update existing values with a new data point */
+
+/**
+ * Incrimentally update existing values with a new data point.
+ */
 void least_squares_update(double x, double y, double *m, double *b);
 
 
-/* 
+/**
-  return the least squares error:
+  @return the least squares error:.
+\f[
 
-              (y[i] - y_hat[i])^2
+    \frac{(y_i - \hat{y}_i)^2}{n}
-              -------------------
+\f]
-                      n
 */
 double least_squares_error(double *x, double *y, int n, double m, double b);
 
 
-/* 
+/**
-  return the maximum least squares error:
+  @return the maximum least squares error.
 
-              (y[i] - y_hat[i])^2
+\f[
+    (y_i - \hat{y}_i)^2
+\f]
 */
 double least_squares_max_error(double *x, double *y, int n, double m, double b);
 

simgear/math/point3d.hxx

@@ -1,7 +1,13 @@
-// point3d.hxx -- a 3d point class.  
+/**
-//
+ * \file point3d.hxx
-// Adapted from algebra3 by Jean-Francois Doue, started October 1998.
+ * A 3d point class (depricated).  This class is depricated and we are
-//
+ * in the process of removing all usage of it in favor of plib's "sg"
+ * library of point, vector, and math routines.  Plib's sg lib is less
+ * object oriented, but integrates more seamlessly with opengl.
+ *
+ * Adapted from algebra3 by Jean-Francois Doue, started October 1998.
+ */
+
 // Copyright (C) 1998  Curtis L. Olson  - curt@me.umn.edu
 //
 // This library is free software; you can redistribute it and/or
@@ -73,11 +79,9 @@ Point3D operator- (const Point3D& p);	            // -p1
 bool operator== (const Point3D& a, const Point3D& b);  // p1 == p2?
 
 
-///////////////////////////
+/**
-//
+ * 3D Point class.
-// 3D Point
+ */
-//
-///////////////////////////
 
 class Point3D {
 
@@ -87,8 +91,7 @@ protected:
 
 public:
 
-    // Constructors
+    /** Default constructor */
-
     Point3D();
     Point3D(const double x, const double y, const double z);
     explicit Point3D(const double d);

simgear/math/polar3d.hxx

@@ -1,5 +1,8 @@
-// polar.hxx -- routines to deal with polar math and transformations
+/**
-//
+ * \file polar3d.hxx
+ * Routines to deal with polar math and transformations.
+ */
+
 // Written by Curtis Olson, started June 1997.
 //
 // Copyright (C) 1997  Curtis L. Olson  - curt@infoplane.com
@@ -22,8 +25,8 @@
 // $Id$
 
 
-#ifndef _POLAR_HXX
+#ifndef _POLAR3D_HXX
-#define _POLAR_HXX
+#define _POLAR3D_HXX
 
 
 #ifndef __cplusplus                                                          
@@ -37,15 +40,23 @@
 #include <simgear/math/point3d.hxx>
 
 
-// Find the Altitude above the Ellipsoid (WGS84) given the Earth
+/** 
-// Centered Cartesian coordinate vector Distances are specified in
+ * Find the Altitude above the Ellipsoid (WGS84) given the Earth
-// meters.
+ * Centered Cartesian coordinate vector Distances are specified in
+ * meters.
+ * @param cp point specified in cartesian coordinates
+ * @return altitude above the (wgs84) earth in meters
+ */
 double sgGeodAltFromCart(const Point3D& cp);
 
 
-// Convert a polar coordinate to a cartesian coordinate.  Lon and Lat
+/**
-// must be specified in radians.  The SG convention is for distances
+ * Convert a polar coordinate to a cartesian coordinate.  Lon and Lat
-// to be specified in meters
+ * must be specified in radians.  The SG convention is for distances
+ * to be specified in meters
+ * @param p point specified in polar coordinates
+ * @return the same point in cartesian coordinates
+ */
 inline Point3D sgPolarToCart3d(const Point3D& p) {
     double tmp = cos( p.lat() ) * p.radius();
 
@@ -55,8 +66,12 @@ inline Point3D sgPolarToCart3d(const Point3D& p) {
 }
 
 
-// Convert a cartesian coordinate to polar coordinates (lon/lat
+/**
-// specified in radians.  Distances are specified in meters.
+ * Convert a cartesian coordinate to polar coordinates (lon/lat
+ * specified in radians.  Distances are specified in meters.
+ * @param cp point specified in cartesian coordinates
+ * @return the same point in polar coordinates
+ */
 inline Point3D sgCartToPolar3d(const Point3D& cp) {
     return Point3D( atan2( cp.y(), cp.x() ),
 		    SGD_PI_2 - 
@@ -65,10 +80,16 @@ inline Point3D sgCartToPolar3d(const Point3D& cp) {
 }
 
 
-// calc new lon/lat given starting lon/lat, and offset radial, and
+/**
-// distance.  NOTE: starting point is specifed in radians, distance is
+ * Calculate new lon/lat given starting lon/lat, and offset radial, and
-// specified in meters (and converted internally to radians)
+ * distance.  NOTE: starting point is specifed in radians, distance is
-// ... assumes a spherical world
+ * specified in meters (and converted internally to radians)
+ * ... assumes a spherical world.
+ * @param orig specified in polar coordinates
+ * @param course offset radial
+ * @param dist offset distance
+ * @return destination point in polar coordinates
+ */
 inline Point3D calc_gc_lon_lat( const Point3D& orig, double course,
 				double dist ) {
     Point3D result;
@@ -101,7 +122,13 @@ inline Point3D calc_gc_lon_lat( const Point3D& orig, double course,
 }
 
 
-// calc course/dist
+/**
+ * Calculate course/dist given two spherical points.
+ * @param start starting point
+ * @param dest ending point
+ * @param course resulting course
+ * @param dist resulting distance
+ */
 inline void calc_gc_course_dist( const Point3D& start, const Point3D& dest, 
 				 double *course, double *dist ) {
     // d = 2*asin(sqrt((sin((lat1-lat2)/2))^2 + 
@@ -157,4 +184,4 @@ inline void calc_gc_course_dist( const Point3D& start, const Point3D& dest,
     *dist = d * SG_RAD_TO_NM * SG_NM_TO_METER;
 }
 
-#endif // _POLAR_HXX
+#endif // _POLAR3D_HXX

simgear/math/sg_geodesy.hxx

@@ -1,8 +1,9 @@
-// sg_geodesy.hxx -- routines to convert between geodetic and geocentric 
+/**
-//                   coordinate systems.
+ * \file sg_geodesy.hxx
-//
+ * Routines to convert between geodetic and geocentric coordinate systems.
-// Copied and adapted directly from LaRCsim/ls_geodesy.c
+ * Copied and adapted directly from LaRCsim/ls_geodesy.c
-//
+ */
+
 // See below for the complete original LaRCsim comments.
 //
 // $Id$
@@ -21,39 +22,37 @@
 #include <simgear/math/polar3d.hxx>
 
 
-// sgGeocToGeod(lat_geoc, radius, *lat_geod, *alt, *sea_level_r)
+/** 
-//     INPUTS:	
+ * Convert from geocentric coordinates to geodetic coordinates
-//         lat_geoc	Geocentric latitude, radians, + = North
+ * @param lat_geoc (in) Geocentric latitude, radians, + = North
-//         radius	C.G. radius to earth center (meters)
+ * @param radius (in) C.G. radius to earth center (meters)
-//
+ * @param lat_geod (out) Geodetic latitude, radians, + = North
-//     OUTPUTS:
+ * @param alt (out) C.G. altitude above mean sea level (meters)
-//         lat_geod	Geodetic latitude, radians, + = North
+ * @param sea_level_r (out) radius from earth center to sea level at
-//         alt		C.G. altitude above mean sea level (meters)
+ *        local vertical (surface normal) of C.G. (meters)
-//         sea_level_r	radius from earth center to sea level at
+ */
-//                      local vertical (surface normal) of C.G. (meters)
-
 void sgGeocToGeod( double lat_geoc, double radius, double
 		   *lat_geod, double *alt, double *sea_level_r );
 
 
-// sgGeodToGeoc( lat_geod, alt, *sl_radius, *lat_geoc )
+/**
-//     INPUTS:	
+ * Convert from geodetic coordinates to geocentric coordinates
-//         lat_geod	Geodetic latitude, radians, + = North
+ * @param lat_geod (in) Geodetic latitude, radians, + = North
-//         alt		C.G. altitude above mean sea level (meters)
+ * @param alt (in) C.G. altitude above mean sea level (meters)
-//
+ * @param sl_radius (out) SEA LEVEL radius to earth center (meters)
-//     OUTPUTS:
+ *        (add Altitude to get true distance from earth center.
-//         sl_radius	SEA LEVEL radius to earth center (meters)
+ * @param lat_geoc (out) Geocentric latitude, radians, + = North
-//                      (add Altitude to get true distance from earth center.
+ */
-//         lat_geoc	Geocentric latitude, radians, + = North
-//
-
 void sgGeodToGeoc( double lat_geod, double alt, double *sl_radius,
 		      double *lat_geoc );
 
 
-// convert a geodetic point lon(radians), lat(radians), elev(meter) to
+/**
-// a cartesian point
+ * Convert a geodetic point lon(radians), lat(radians), elev(meter) to
-
+ * a cartesian point.
+ * @param geodetic point
+ * @return cartesian point
+ */
 inline Point3D sgGeodToCart(const Point3D& geod) {
     double gc_lon, gc_lat, sl_radius;
 
@@ -71,8 +70,18 @@ inline Point3D sgGeodToCart(const Point3D& geod) {
 }
 
 
-// given, alt, lat1, lon1, az1 and distance (s), calculate lat2, lon2
+/**
-// and az2.  Lat, lon, and azimuth are in degrees.  distance in meters
+ * Given a starting position and an offset radial and distance,
+ * calculate an ending positon on a wgs84 ellipsoid.
+ * @param alt (in) meters
+ * @param lat1 (in) degrees
+ * @param lon1 (in) degrees
+ * @param az1 (in) degrees
+ * @param s (in) distance in meters
+ * @param lat2 (out) degrees
+ * @param lon2 (out) degrees
+ * @param az2 (out) return course in degrees
+ */
 int geo_direct_wgs_84 ( double alt, double lat1, double lon1, double az1, 
 			double s, double *lat2, double *lon2,  double *az2 );
 

simgear/math/sg_memory.h

@@ -1,5 +1,9 @@
-// fg_memory.h -- memcpy/bcopy portability declarations
+/**
-//
+ * \file sg_memory.h
+ * memcpy/bcopy portability declarations (not actually used by anything
+ * as best as I can tell.
+ */
+
 // This library is free software; you can redistribute it and/or
 // modify it under the terms of the GNU Library General Public
 // License as published by the Free Software Foundation; either
@@ -18,8 +22,8 @@
 // $Id$
 
 
-#ifndef _FG_MEMORY_H
+#ifndef _SG_MEMORY_H
-#define _FG_MEMORY_H
+#define _SG_MEMORY_H
 
 #ifdef HAVE_CONFIG_H
 #  include <config.h>
@@ -31,15 +35,15 @@
 #    include <memory.h>
 #  endif
 
-#  define fgmemcmp            memcmp
+#  define sgmemcmp            memcmp
-#  define fgmemcpy            memcpy
+#  define sgmemcpy            memcpy
-#  define fgmemzero(dest,len) memset(dest,0,len)
+#  define sgmemzero(dest,len) memset(dest,0,len)
 
 #elif defined(HAVE_BCOPY)
 
-#  define fgmemcmp              bcmp
+#  define sgmemcmp              bcmp
-#  define fgmemcpy(dest,src,n)  bcopy(src,dest,n)
+#  define sgmemcpy(dest,src,n)  bcopy(src,dest,n)
-#  define fgmemzero             bzero
+#  define sgmemzero             bzero
 
 #else
 
@@ -49,12 +53,12 @@
  */
 
 #  include <zutil.h>
-#  define fgmemcmp zmemcmp
+#  define sgmemcmp zmemcmp
-#  define fgmemcpy zmemcpy
+#  define sgmemcpy zmemcpy
-#  define fgmemzero zmemzero
+#  define sgmemzero zmemzero
 
 #endif
 
-#endif // _FG_MEMORY_H
+#endif // _SG_MEMORY_H
 
 

simgear/math/sg_random.c

@@ -41,7 +41,7 @@
 
 #ifdef __SUNPRO_CC
     extern "C" {
-	long int random(void);
+	long int random();
 	void srandom(unsigned int seed);
     }
 #endif
@@ -49,7 +49,7 @@
 
 // Seed the random number generater with time() so we don't see the
 // same sequence every time
-void sg_srandom_time(void) {
+void sg_srandom_time() {
 #ifdef HAVE_RAND
     srand(time(NULL));
 #else
@@ -70,7 +70,7 @@ void sg_srandom( unsigned int seed ) {
 
 
 // return a random number between [0.0, 1.0)
-double sg_random(void) {
+double sg_random() {
 #ifdef HAVE_RAND
     return(rand() / (double)RAND_MAX);
 #else

simgear/math/sg_random.h

@@ -1,5 +1,8 @@
-// sg_random.h -- routines to handle random number generation
+/**
-//
+ * \file sg_random.h
+ * Routines to handle random number generation and hide platform differences.
+ */
+
 // Written by Curtis Olson, started July 1997.
 //
 // Copyright (C) 1997  Curtis L. Olson  - curt@infoplane.com
@@ -31,16 +34,24 @@ extern "C" {
 #endif                                   
 
 
-// Seed the random number generater with time() so we don't see the
+/**
-// same sequence every time
+ * Seed the random number generater with time() so we don't see the
-void sg_srandom_time(void);
+ * same sequence every time.
+ */
+void sg_srandom_time();
 
-// Seed the random number generater with your own seed so can set up
+/**
-// repeatable randomization.
+ * Seed the random number generater with your own seed so can set up
+ * repeatable randomization.
+ * @param seed random number generator seed
+ */
 void sg_srandom( unsigned int seed );
 
-// return a random number between [0.0, 1.0)
+/**
-double sg_random(void);
+ * Return a random number between [0.0, 1.0)
+ * @return next "random" number in the "random" sequence
+ */
+double sg_random();
 
 
 #ifdef __cplusplus

simgear/math/sg_types.hxx

@@ -1,5 +1,8 @@
-// fg_types.hxx -- commonly used types I don't want to have to keep redefining
+/**
-//
+ * \file sg_types.hxx
+ * Commonly used types I don't want to have to keep redefining.
+ */
+
 // Written by Curtis Olson, started March 1999.
 //
 // Copyright (C) 1999  Curtis L. Olson  - curt@flightgear.org
@@ -22,8 +25,8 @@
 // $Id$
 
 
-#ifndef _FG_TYPES_HXX
+#ifndef _SG_TYPES_HXX
-#define _FG_TYPES_HXX
+#define _SG_TYPES_HXX
 
 
 #ifndef __cplusplus                                                          
@@ -41,20 +44,26 @@
 SG_USING_STD(vector);
 SG_USING_STD(string);
 
-
+/** STL vector list of ints */
 typedef vector < int > int_list;
 typedef int_list::iterator int_list_iterator;
 typedef int_list::const_iterator const_int_list_iterator;
 
+/** STL vector list of Point3D */
 typedef vector < Point3D > point_list;
 typedef point_list::iterator point_list_iterator;
 typedef point_list::const_iterator const_point_list_iterator;
 
+/** STL vector list of strings */
 typedef vector < string > string_list;
 typedef string_list::iterator string_list_iterator;
 typedef string_list::const_iterator const_string_list_iterator;
 
 
+/**
+ * Simple 2d point class where members can be accessed as x, dist, or lon
+ * and y, theta, or lat
+ */
 class point2d {
 public:
     union {
@@ -70,5 +79,5 @@ public:
 };
 
 
-#endif // _FG_TYPES_HXX
+#endif // _SG_TYPES_HXX
 

simgear/math/vector.hxx

@@ -1,5 +1,8 @@
-// vector.hxx -- additional vector routines
+/**
-//
+ * \file vector.hxx
+ * Additional vector routines.
+ */
+
 // Written by Curtis Olson, started December 1997.
 //
 // Copyright (C) 1997  Curtis L. Olson  - curt@infoplane.com
@@ -39,6 +42,13 @@
 #include <plib/sg.h>
 
 
+/**
+ * Map a vector onto a plane.
+ * @param normal (in) normal vector for the plane
+ * @param v0 (in) a point on the plane
+ * @param vec (in) the vector to map onto the plane
+ * @param result (out) the result vector
+ */
 inline void sgmap_vec_onto_cur_surface_plane( sgVec3 normal, 
 					      sgVec3 v0, 
 					      sgVec3 vec,
@@ -84,6 +94,11 @@ inline void sgmap_vec_onto_cur_surface_plane( sgVec3 normal,
 }
 
 
+/**
+ * Copy and negate a vector.
+ * @param dst (out) result vector
+ * @param src (in) input vector
+ */
 inline void sgCopyNegateVec4( sgVec4 dst, sgVec4 src )
 {
 	dst [ 0 ] = -src [ 0 ] ;
@@ -92,31 +107,64 @@ inline void sgCopyNegateVec4( sgVec4 dst, sgVec4 src )
 	dst [ 3 ] = -src [ 3 ] ;
 }
 
-// Given a point p, and a line through p0 with direction vector d,
+/**
-// find the closest point (p1) on the line
+ * Given a point p, and a line through p0 with direction vector d,
+ * find the closest point (p1) on the line (float version).
+ * @param p1 (out) closest point to p on the line
+ * @param p (in) original point
+ * @param p0 (in) point on the line
+ * @param d (in) vector defining line direction
+ */
 void sgClosestPointToLine( sgVec3 p1, const sgVec3 p, const sgVec3 p0,
 			   const sgVec3 d );
 
-// Given a point p, and a line through p0 with direction vector d,
+/**
-// find the closest point (p1) on the line
+ * Given a point p, and a line through p0 with direction vector d,
+ * find the closest point (p1) on the line (double version).
+ * @param p1 (out) closest point to p on the line
+ * @param p (in) original point
+ * @param p0 (in) point on the line
+ * @param d (in) vector defining line direction
+ */
 void sgdClosestPointToLine( sgdVec3 p1, const sgdVec3 p, const sgdVec3 p0,
 			    const sgdVec3 d );
 
-// Given a point p, and a line through p0 with direction vector d,
+/**
-// find the shortest distance (squared) from the point to the line
+ * Given a point p, and a line through p0 with direction vector d,
+ * find the shortest distance (squared) from the point to the line (float
+ * version.)
+ * @param p (in) original point
+ * @param p0 (in) point on the line
+ * @param d (in) vector defining line direction
+ * @return shortest distance (squared) from p to line
+ */
 double sgClosestPointToLineDistSquared( const sgVec3 p, const sgVec3 p0,
 					const sgVec3 d );
 
-// Given a point p, and a line through p0 with direction vector d,
+/**
-// find the shortest distance (squared) from the point to the line
+ * Given a point p, and a line through p0 with direction vector d,
+ * find the shortest distance (squared) from the point to the line (double
+ * version.)
+ * @param p (in) original point
+ * @param p0 (in) point on the line
+ * @param d (in) vector defining line direction
+ * @return shortest distance (squared) from p to line
+ */
 double sgdClosestPointToLineDistSquared( const sgdVec3 p, const sgdVec3 p0,
 					 const sgdVec3 d );
 
-// This is same as
+/**
-// sgMakeMatTrans4( sgMat4 sgTrans, sgVec3 trans )
+ * This is same as:
-// sgPostMultMat4( sgMat, sgTRANS );
+ *
+ * <li> sgMakeMatTrans4( sgMat4 sgTrans, sgVec3 trans )
+ * <li> sgPostMultMat4( sgMat4 src, sgTRANS );
+ *
+ * @param src starting sgMat4 matrix
+ * @param trans translation vector
+ */
 void sgPostMultMat4ByTransMat4( sgMat4 src, const sgVec3 trans );
 
+
 #endif // _VECTOR_HXX