From 51ef4568dd248a6917720a386e658610958e1512 Mon Sep 17 00:00:00 2001 From: curt Date: Tue, 3 Jun 2003 18:32:51 +0000 Subject: [PATCH] Various documentation tweaks and additions. --- Doxyfile | 2 + DoxygenMain.cxx | 53 +++++++++++++++++------ simgear/math/sg_geodesy.hxx | 15 +++++-- simgear/screen/texture.cxx | 3 +- simgear/screen/texture.hxx | 15 +++++++ simgear/timing/geocoord.cxx | 18 ++++---- simgear/timing/geocoord.h | 34 +++++++-------- simgear/timing/sg_time.cxx | 12 +++--- simgear/timing/sg_time.hxx | 2 +- simgear/timing/timezone.cxx | 22 +++++----- simgear/timing/timezone.h | 86 +++++++++++++++++++++++++++---------- 11 files changed, 176 insertions(+), 86 deletions(-) diff --git a/Doxyfile b/Doxyfile index a258deaf..e00e7963 100644 --- a/Doxyfile +++ b/Doxyfile @@ -308,12 +308,14 @@ INPUT = \ simgear/magvar \ simgear/math \ simgear/misc \ + simgear/props \ simgear/route \ simgear/scene \ simgear/screen \ simgear/serial \ simgear/sg_inlines.h \ simgear/sg_traits.hxx \ + simgear/sound \ simgear/threads \ simgear/timing \ simgear/xml diff --git a/DoxygenMain.cxx b/DoxygenMain.cxx index 37540088..5ef9e167 100644 --- a/DoxygenMain.cxx +++ b/DoxygenMain.cxx @@ -18,29 +18,59 @@ * Some of the functionality provide includes * * - Compiler and platform abstractions for many tricky differences. - * - A whole earth tiling/indexing scheme. + * (compiler.h) + * + * - A whole earth tiling/indexing scheme. (SGBucket) + * * - A console debugging output scheme that tracks severity and * category that can be completely compiled out for a final build release. - * - Code to manage "real" time and time zones. + * (logstream.hxx) + * + * - Code to manage "real" time (SGTime), time zones (SGTimeZone), and + * millesecond time differences (SGTimeStamp). + * * - Code to calculate accurate positions of sun, moon, stars, and * planets for a given time, date, season, earth location, etc. - * - Simple serial, file, and network I/O abstractions - * - Code to calculate magnetic variation. - * - A variety of coordinate conversion, vector, matrix type math routines. - * - An abstraction to hide platform dependent path naming schemes. + * (SGEphemeris) + * + * - Simple serial (SGSerial), file (SGFile), socket (SGSocket), and + * UDP socket (SGSocketUDP) I/O abstractions. + * + * - Code to calculate magnetic variation. (SGMagVar) + * + * - A variety of classes and functions for interpolation tables + * (SGInterpTable), least squares computation (leastsqs.hxx), 3D + * point/vectors (Point3D), 3D polar math and conversions (polar3d.hxx), + * WGS-84 math and conversions (sg_geodesy.hxx), random number abstraction + * (sg_random.h), STL conglomerates for common list types (sg_types.hxx), + * and other vector and linear algebra routines (vector.hxx) + * + * - An abstraction to hide platform dependent path naming schemes. (SGPath) + * * - A C++ streams wrapper to handle compress input/output streams. + * (sg_gzifstream) + * * - An optimized "property manager" which associates ascii property * names with their corresponding value. This can be a great way to build * loose linkages between modules, or build linkages/connections that can - * be determined from config files or at runtime. + * be determined from config files or at runtime. (SGPropertyNode) + * Also included is a set of functions to dump the property tree into a + * standard xml file and subsequently read/parse a standard xml file and + * rebuild the associated property tree. (props_io.hxx) + * * - Scene management and drawing routines: * - material property management * - object management * - terrain tile management and paging * - sky dome rendering (with ephemeral objects) - * - Code to handle screen dumps (and ultra-hires tile rendered screen dumps) - * - A sound effects manager. + * + * - Code to handle screen dumps (screen-dump.hxx) and ultra-hires + * tile rendered screen dumps (tr.h) + * + * - A sound effects manager. (SGSoundMgr, SGSimpleSound, SGSound) + * * - A threading abstraction. + * * - A simple but highly functional XML parser that interfaces nicely * with the property manager. @@ -69,10 +99,5 @@ * * SimGear is licensed under the terms of the LGPL - * \section install Installation - * - * \subsection step1 Step 1: Opening the box - * - * etc... */ diff --git a/simgear/math/sg_geodesy.hxx b/simgear/math/sg_geodesy.hxx index f3be1a39..21acaa35 100644 --- a/simgear/math/sg_geodesy.hxx +++ b/simgear/math/sg_geodesy.hxx @@ -88,9 +88,18 @@ int geo_direct_wgs_84 ( const double& alt, const double& lat1, double *az2 ); -// given alt, lat1, lon1, lat2, lon2, calculate starting and ending -// az1, az2 and distance (s). Lat, lon, and azimuth are in degrees. -// distance in meters +/** + * Given an altitude and two sets of (lat, lon) calculate great circle + * distance between them as well as the starting and ending azimuths. + * @param alt (in) meters + * @param lat1 (in) degrees + * @param lon1 (in) degrees + * @param lat2 (in) degrees + * @param lon2 (in) degrees + * @param az1 (out) start heading degrees + * @param az2 (out) end heading degrees + * @param s (out) distance meters + */ int geo_inverse_wgs_84( const double& alt, const double& lat1, const double& lon1, const double& lat2, const double& lon2, double *az1, double *az2, diff --git a/simgear/screen/texture.cxx b/simgear/screen/texture.cxx index 4917399e..58f69ef6 100644 --- a/simgear/screen/texture.cxx +++ b/simgear/screen/texture.cxx @@ -1,5 +1,4 @@ -/** - * \file texture.cxx +/* * Texture manipulation routines * * Copyright (c) Mark J. Kilgard, 1997. diff --git a/simgear/screen/texture.hxx b/simgear/screen/texture.hxx index 2a1b5c5c..ec41b2ce 100644 --- a/simgear/screen/texture.hxx +++ b/simgear/screen/texture.hxx @@ -1,3 +1,14 @@ +/** + * \file texture.hxx + * Texture manipulation routines + * + * Copyright (c) Mark J. Kilgard, 1997. + * Code added in april 2003 by Erik Hofman + * + * This program is freely distributable without licensing fees + * and is provided without guarantee or warrantee expressed or + * implied. This program is -not- in the public domain. + */ #ifndef __SG_TEXTURE_HXX #define __SG_TEXTURE_HXX 1 @@ -7,6 +18,10 @@ #include +/** + * A class to encapsulate all the info surrounding an OpenGL texture + * and also query various info and load various file formats + */ class SGTexture { private: diff --git a/simgear/timing/geocoord.cxx b/simgear/timing/geocoord.cxx index a52d26d0..b904ca05 100644 --- a/simgear/timing/geocoord.cxx +++ b/simgear/timing/geocoord.cxx @@ -22,7 +22,7 @@ /************************************************************************* * * This file defines a small and simple class to store geocentric - * coordinates. Basically, class GeoCoord is intended as a base class for + * coordinates. Basically, class SGGeoCoord is intended as a base class for * any kind of of object, that can be categorized according to its * location on earth, be it navaids, or aircraft. This class for originally * written for FlightGear, in order to store Timezone control points. @@ -31,13 +31,13 @@ #include "geocoord.h" #include -GeoCoord::GeoCoord(const GeoCoord& other) +SGGeoCoord::SGGeoCoord(const SGGeoCoord& other) { lat = other.lat; lon = other.lon; } -// double GeoCoord::getAngle(const GeoCoord& other) const +// double SGGeoCoord::getAngle(const SGGeoCoord& other) const // { // Vector first( getX(), getY(), getZ()); // Vector secnd(other.getX(), other.getY(), other.getZ()); @@ -57,11 +57,11 @@ GeoCoord::GeoCoord(const GeoCoord& other) // return angle; // } -// GeoCoord* GeoCoordContainer::getNearest(const GeoCoord& ref) const +// SGGeoCoord* SGGeoCoordContainer::getNearest(const SGGeoCoord& ref) const // { // float angle, maxAngle = 180; -// GeoCoordVectorConstIterator i, nearest; +// SGGeoCoordVectorConstIterator i, nearest; // for (i = data.begin(); i != data.end(); i++) // { // angle = SGD_RADIANS_TO_DEGREES * (*i)->getAngle(ref); @@ -75,12 +75,12 @@ GeoCoord::GeoCoord(const GeoCoord& other) // } -GeoCoord* GeoCoordContainer::getNearest(const GeoCoord& ref) const +SGGeoCoord* SGGeoCoordContainer::getNearest(const SGGeoCoord& ref) const { sgVec3 first, secnd; float dist, maxDist=SG_MAX; sgSetVec3( first, ref.getX(), ref.getY(), ref.getZ()); - GeoCoordVectorConstIterator i, nearest; + SGGeoCoordVectorConstIterator i, nearest; for (i = data.begin(); i != data.end(); i++) { sgSetVec3(secnd, (*i)->getX(), (*i)->getY(), (*i)->getZ()); @@ -95,9 +95,9 @@ GeoCoord* GeoCoordContainer::getNearest(const GeoCoord& ref) const } -GeoCoordContainer::~GeoCoordContainer() +SGGeoCoordContainer::~SGGeoCoordContainer() { - GeoCoordVectorIterator i = data.begin(); + SGGeoCoordVectorIterator i = data.begin(); while (i != data.end()) delete *i++; } diff --git a/simgear/timing/geocoord.h b/simgear/timing/geocoord.h index ce9dc1e9..0dc188c0 100644 --- a/simgear/timing/geocoord.h +++ b/simgear/timing/geocoord.h @@ -47,17 +47,17 @@ SG_USING_NAMESPACE(std); #include -class GeoCoord +class SGGeoCoord { protected: float lat; float lon; public: - GeoCoord() { lat = 0.0; lon = 0.0;}; - GeoCoord(float la, float lo) { lat = la; lon = lo;}; - GeoCoord(const GeoCoord& other); - virtual ~GeoCoord() {}; + SGGeoCoord() { lat = 0.0; lon = 0.0;}; + SGGeoCoord(float la, float lo) { lat = la; lon = lo;}; + SGGeoCoord(const SGGeoCoord& other); + virtual ~SGGeoCoord() {}; void set(float la, float lo) { lat = la; lon = lo; }; float getLat() const { return lat; }; @@ -67,32 +67,32 @@ public: float getZ() const { return sin(SGD_DEGREES_TO_RADIANS*lat); }; - //double getAngle(const GeoCoord& other) const; + //double getAngle(const SGGeoCoord& other) const; virtual void print() {} ; virtual const char * getDescription() {return 0;}; }; -typedef vector GeoCoordVector; -typedef vector::iterator GeoCoordVectorIterator; -typedef vector::const_iterator GeoCoordVectorConstIterator; +typedef vector SGGeoCoordVector; +typedef vector::iterator SGGeoCoordVectorIterator; +typedef vector::const_iterator SGGeoCoordVectorConstIterator; /************************************************************************ - * GeoCoordContainer is a simple container class, that stores objects - * derived from GeoCoord. Basically, it is a wrapper around an STL vector, + * SGGeoCoordContainer is a simple container class, that stores objects + * derived from SGGeoCoord. Basically, it is a wrapper around an STL vector, * with some added functionality ***********************************************************************/ -class GeoCoordContainer +class SGGeoCoordContainer { protected: - GeoCoordVector data; + SGGeoCoordVector data; public: - GeoCoordContainer() {}; - virtual ~GeoCoordContainer(); + SGGeoCoordContainer() {}; + virtual ~SGGeoCoordContainer(); - const GeoCoordVector& getData() const { return data; }; - GeoCoord* getNearest(const GeoCoord& ref) const; + const SGGeoCoordVector& getData() const { return data; }; + SGGeoCoord* getNearest(const SGGeoCoord& ref) const; }; diff --git a/simgear/timing/sg_time.cxx b/simgear/timing/sg_time.cxx index 3f43c9a7..05f00317 100644 --- a/simgear/timing/sg_time.cxx +++ b/simgear/timing/sg_time.cxx @@ -94,10 +94,10 @@ void SGTime::init( double lon, double lat, zone.append( "zone.tab" ); SG_LOG( SG_EVENT, SG_INFO, "Reading timezone info from: " << zone.str() ); - tzContainer = new TimezoneContainer( zone.c_str() ); + tzContainer = new SGTimeZoneContainer( zone.c_str() ); - GeoCoord location( SGD_RADIANS_TO_DEGREES * lat, SGD_RADIANS_TO_DEGREES * lon ); - GeoCoord* nearestTz = tzContainer->getNearest(location); + SGGeoCoord location( SGD_RADIANS_TO_DEGREES * lat, SGD_RADIANS_TO_DEGREES * lon ); + SGGeoCoord* nearestTz = tzContainer->getNearest(location); SGPath name( root ); name.append( nearestTz->getDescription() ); @@ -129,7 +129,7 @@ SGTime::SGTime() { SGTime::~SGTime() { if ( tzContainer != NULL ) { - TimezoneContainer *tmp = tzContainer; + SGTimeZoneContainer *tmp = tzContainer; tzContainer = NULL; delete tmp; } @@ -290,8 +290,8 @@ void SGTime::updateLocal( double lon, double lat, const string& root ) { } time_t currGMT; time_t aircraftLocalTime; - GeoCoord location( SGD_RADIANS_TO_DEGREES * lat, SGD_RADIANS_TO_DEGREES * lon ); - GeoCoord* nearestTz = tzContainer->getNearest(location); + SGGeoCoord location( SGD_RADIANS_TO_DEGREES * lat, SGD_RADIANS_TO_DEGREES * lon ); + SGGeoCoord* nearestTz = tzContainer->getNearest(location); SGPath zone( root ); zone.append ( nearestTz->getDescription() ); zonename = zone.str(); diff --git a/simgear/timing/sg_time.hxx b/simgear/timing/sg_time.hxx index fa0ab060..bf208475 100644 --- a/simgear/timing/sg_time.hxx +++ b/simgear/timing/sg_time.hxx @@ -69,7 +69,7 @@ class SGTime { private: // tzContainer stores all the current Timezone control points/ - TimezoneContainer* tzContainer; + SGTimeZoneContainer* tzContainer; // Points to the current local timezone name; string zonename; diff --git a/simgear/timing/timezone.cxx b/simgear/timing/timezone.cxx index d8ef91d2..aac090a4 100644 --- a/simgear/timing/timezone.cxx +++ b/simgear/timing/timezone.cxx @@ -21,7 +21,7 @@ /************************************************************************* * - * Timezone is derived from geocoord, and stores the timezone centerpoint, + * SGTimeZone is derived from geocoord, and stores the timezone centerpoint, * as well as the countrycode and the timezone descriptor. The latter is * used in order to get the local time. * @@ -32,16 +32,16 @@ #include #include "timezone.h" -Timezone::Timezone(float la, float lo, char* cc, char* desc) : - GeoCoord(la, lo) +SGTimeZone::SGTimeZone(float la, float lo, char* cc, char* desc) : + SGGeoCoord(la, lo) { countryCode = cc; descriptor = desc; } /* Build a timezone object from a textline in zone.tab */ -Timezone::Timezone(const char *infoString) : - GeoCoord() +SGTimeZone::SGTimeZone(const char *infoString) : + SGGeoCoord() { int i = 0; while (infoString[i] != '\t') @@ -111,7 +111,7 @@ Timezone::Timezone(const char *infoString) : } /* the copy constructor */ -Timezone::Timezone(const Timezone& other) +SGTimeZone::SGTimeZone(const SGTimeZone& other) { lat = other.getLat(); lon = other.getLon(); @@ -120,9 +120,9 @@ Timezone::Timezone(const Timezone& other) } -/********* Member functions for TimezoneContainer class ********/ +/********* Member functions for SGTimeZoneContainer class ********/ -TimezoneContainer::TimezoneContainer(const char *filename) +SGTimeZoneContainer::SGTimeZoneContainer(const char *filename) { char buffer[256]; FILE* infile = fopen(filename, "rb"); @@ -144,16 +144,16 @@ TimezoneContainer::TimezoneContainer(const char *filename) } } if (buffer[0]) { - data.push_back(new Timezone(buffer)); + data.push_back(new SGTimeZone(buffer)); } } if ( errno ) { - perror( "TimezoneContainer()" ); + perror( "SGTimeZoneContainer()" ); errno = 0; } } } -TimezoneContainer::~TimezoneContainer() +SGTimeZoneContainer::~SGTimeZoneContainer() { } diff --git a/simgear/timing/timezone.h b/simgear/timing/timezone.h index 5d3035d5..e286d857 100644 --- a/simgear/timing/timezone.h +++ b/simgear/timing/timezone.h @@ -19,13 +19,11 @@ * **************************************************************************/ -/************************************************************************* +/** \file timezone.h * - * Timezone is derived from geocoord, and stores the timezone centerpoint, - * as well as the countrycode and the timezone descriptor. The latter is - * used in order to get the local time. + * Provides SGTimeZone and SGTimeZoneContainer * - ************************************************************************/ + */ #ifndef _TIMEZONE_H_ #define _TIMEZONE_H_ @@ -34,39 +32,81 @@ #include -class Timezone : public GeoCoord +/** + * SGTimeZone is derived from geocoord, and stores the timezone centerpoint, + * as well as the countrycode and the timezone descriptor. The latter is + * used in order to get the local time. + * + */ + +class SGTimeZone : public SGGeoCoord { + private: + string countryCode; string descriptor; public: - Timezone() : - GeoCoord() - { - countryCode.erase(); - descriptor.erase(); + + /** + * Default constructor. + */ + SGTimeZone() : SGGeoCoord() + { + countryCode.erase(); + descriptor.erase(); }; - Timezone(float la, float lo, char* cc, char* desc); - Timezone(const char *infoString); - Timezone(const Timezone &other); - virtual ~Timezone() { }; + + /** + * Build a timezone object with a specifed latitude, longitude, country + * code, and descriptor + * @param la latitude + * @param lo longitude + * @param cc country code + * @param desc descriptor + */ + SGTimeZone(float la, float lo, char* cc, char* desc); + + /** + * Build a timezone object from a textline in zone.tab + * @param infoString the textline from zone.tab + */ + SGTimeZone(const char *infoString); + + /** + * The copy constructor + * @param other the source object + */ + SGTimeZone(const SGTimeZone &other); + + /** + * Virutal destructor + */ + virtual ~SGTimeZone() { }; + /** + * Print the descriptor string + */ + virtual void print() { printf("%s", descriptor.c_str()); } - virtual void print() { printf("%s", descriptor.c_str());}; - virtual const char * getDescription() { return descriptor.c_str(); }; + /** + * Return the descriptor string + * @return descriptor string (char array) + */ + virtual const char * getDescription() { return descriptor.c_str(); }; }; -/************************************************************************ - * Timezone container is derived from GeoCoordContainer, and has some +/** + * SGTimeZoneContainer is derived from SGGeoCoordContainer, and has some * added functionality. - ************************************************************************/ + */ -class TimezoneContainer : public GeoCoordContainer +class SGTimeZoneContainer : public SGGeoCoordContainer { public: - TimezoneContainer(const char *filename); - virtual ~TimezoneContainer(); + SGTimeZoneContainer(const char *filename); + virtual ~SGTimeZoneContainer(); }; -- 2.39.5