Index: /trunk/archive/pslib/include/psAstrom.h =================================================================== --- /trunk/archive/pslib/include/psAstrom.h (revision 246) +++ /trunk/archive/pslib/include/psAstrom.h (revision 247) @@ -2,17 +2,8 @@ #define PS_ASTROM_H -/* Include array declaration macros */ -#include "psArray.h" -/* Include standard array definitions */ -#include "psStdArrays.h" -/* Include position definitions */ -#include "psPosition.h" -/* Include colour definitions */ -#include "psColour.h" -/* Include matrix definitions */ -#include "psMatrix.h" -/* Include polynomial definitions */ -#include "psFunctions.h" - +/** \file psAstrom.h + * \brief Astrometric transformations + * \ingroup AstroGroup + */ /***********************************************************************************************************/ Index: /trunk/archive/pslib/include/psBitMask.h =================================================================== --- /trunk/archive/pslib/include/psBitMask.h (revision 246) +++ /trunk/archive/pslib/include/psBitMask.h (revision 247) @@ -1,4 +1,9 @@ # if !defined (PS_BIT_MASK_H) # define PS_BIT_MASK_H + +/** \file psBitMask.h + * \brief Bitmask manipulations and operations. + * \ingroup MathGroup + */ /** A bitmask of arbitrary length. */ Index: /trunk/archive/pslib/include/psDateTime.h =================================================================== --- /trunk/archive/pslib/include/psDateTime.h (revision 246) +++ /trunk/archive/pslib/include/psDateTime.h (revision 247) @@ -2,5 +2,8 @@ #define PS_DATE_TIME_H -/* Dates and Times */ +/** \file psDateTime.h + * \brief Dates and Times + * \ingroup AstroGroup + */ /** Get current MJD, for a timestamp */ Index: /trunk/archive/pslib/include/psDlist.h =================================================================== --- /trunk/archive/pslib/include/psDlist.h (revision 246) +++ /trunk/archive/pslib/include/psDlist.h (revision 247) @@ -1,6 +1,8 @@ #if !defined(PS_DLIST_H) #define PS_DLIST_H -/* - * Support for doubly linked lists + +/** \file psDlist.h + * \brief Support for doubly linked lists + * \ingroup DataGroup */ Index: /trunk/archive/pslib/include/psFFT.h =================================================================== --- /trunk/archive/pslib/include/psFFT.h (revision 246) +++ /trunk/archive/pslib/include/psFFT.h (revision 247) @@ -2,7 +2,8 @@ #define PS_FFT_H -#include "psStdArrays.h" - -/* Fourier Transform functions */ +/** \file psFFT.h + * \brief Fourier Transform functions + * \ingroup MathGroup + */ /** Return Fourier Transform of an array */ Index: /trunk/archive/pslib/include/psFunctions.h =================================================================== --- /trunk/archive/pslib/include/psFunctions.h (revision 246) +++ /trunk/archive/pslib/include/psFunctions.h (revision 247) @@ -2,9 +2,11 @@ #define PS_FUNCTIONS_H -#include "psStdArrays.h" +/** \file psFunctions.h + * \brief Standard Mathematical Functions. + * \ingroup MathGroup + */ -/* Standard Functions */ - -/** Gaussian. Note that this is not a Gaussian deviate */ +/** evaluate a non-normalized Gaussian with the given mean and sigma at the given coordianate. Note that this + is not a Gaussian deviate. The evaluated Gaussian is: \f[ exp(-\frac{(x-mean)^2}{2\sigma^2}) \f] */ float psGaussian(float x, //!< Value at which to evaluate Index: /trunk/archive/pslib/include/psHash.h =================================================================== --- /trunk/archive/pslib/include/psHash.h (revision 246) +++ /trunk/archive/pslib/include/psHash.h (revision 247) @@ -2,4 +2,10 @@ #define PS_HASH_H +/** \file psHash.h + * \brief Hash Table manipulation + * \ingroup DataGroup + */ + +/** DO WE NEED TO DEFINE HashTable? */ typedef struct HashTable psHash; //!< Opaque type for a hash table Index: /trunk/archive/pslib/include/psLogMsg.h =================================================================== --- /trunk/archive/pslib/include/psLogMsg.h (revision 246) +++ /trunk/archive/pslib/include/psLogMsg.h (revision 247) @@ -1,5 +1,9 @@ #if !defined(PS_LOG_MSG_H) #define PS_LOG_MSG_H -#include + +/** \file psLogMsg.h + * \brief log messaging facilities + * \ingroup SystemGroup + */ enum { PS_LOG_ABORT = 0, PS_LOG_ERROR, PS_LOG_WARN, PS_LOG_INFO }; //!< Status codes for log messages Index: /trunk/archive/pslib/include/psMath.h =================================================================== --- /trunk/archive/pslib/include/psMath.h (revision 246) +++ /trunk/archive/pslib/include/psMath.h (revision 247) @@ -2,10 +2,19 @@ #define PS_MATH_H -/** in this method, the data types (psImage, psVector) include embedded information about their data type in - * the structure. The constant value is then handled by calling the psScalar function which returns a private - * scalar data type which is always freed by the code. This forces the layout of the data structures to be - * consistent, with the type information as the first entry. We can then define a data type which is - * completely flat and can be used to check on the data type of the data. +/** \file psMath.h + * \brief math operators between PSLib data types + * \ingroup MathGroup */ + +/** private structure used to pass constant values into the math operators. */ +typedef struct { + psType type; ///< data type information + union { + int i; ///< integer value entry + float f; ///< float value entry + double d; ///< double value entry + complex float c; ///< complex value entry + } +} p_psScalar; /** Perform a binary operation on two data items (psImage, psVector, psScalar). */ @@ -24,5 +33,5 @@ ); -/** create a psType-ed structure from a constant value. */ +/** create a psType-ed structure from a constant double value. */ p_ps_Scalar * psScalar (double value); @@ -34,13 +43,10 @@ ); -typedef struct { - psType type; - union { - int i; - float f; - double d; - complex float c; - } -} p_psScalar; +/** the functions defined here can operate on the basic PSLib data types: psImage, psVector, XXX. These data + * types include embedded information about their type in the structure. Constant values are handled by + * wrapping the value in the psScalar function, which returns a private scalar data type, p_ps_Scalar, which + * is always freed by the function. The return value type can be determined by casting the return to psType + * and checking the type entry. + */ /* examples of usage: @@ -66,5 +72,4 @@ */ - #endif Index: /trunk/archive/pslib/include/psMatrix.h =================================================================== --- /trunk/archive/pslib/include/psMatrix.h (revision 246) +++ /trunk/archive/pslib/include/psMatrix.h (revision 247) @@ -1,4 +1,9 @@ #if !defined(PS_MATRIX_H) #define PS_MATRIX_H + +/** \file psMatrix.h + * \brief matrix math operators + * \ingroup MathGroup + */ /** A matrix */ Index: /trunk/archive/pslib/include/psMemory.h =================================================================== --- /trunk/archive/pslib/include/psMemory.h (revision 246) +++ /trunk/archive/pslib/include/psMemory.h (revision 247) @@ -1,11 +1,14 @@ #if !defined(PS_MEMORY_H) #define PS_MEMORY_H -#include -/** - * Book-keeping data for storage allocator. - * - * N.b. sizeof(psMemBlock) must be chosen such that if ptr is a pointer - * returned by malloc, then ((char *)ptr + sizeof(psMemBlock)) is properly - * aligned for all storage types. + +/** \file psMemory.h + * \brief Memory alloc/free routines + * \ingroup SystemGroup + */ + +/** Book-keeping data for storage allocator. + * N.b. sizeof(psMemBlock) must be chosen such that if ptr is a pointer + * returned by malloc, then ((char *)ptr + sizeof(psMemBlock)) is properly + * aligned for all storage types. */ typedef struct { @@ -18,24 +21,16 @@ } psMemBlock; -/** */ +/** prototype of a basic callback used by memory functions */ typedef int (*psMemCallback)(const psMemBlock *ptr); -typedef void (*psMemProblemCallback)(const psMemBlock *ptr, - const char *file, int lineno); + +/** prototype of a callback used in error conditions */ +typedef void (*psMemProblemCallback)(const psMemBlock *ptr, const char *file, int lineno); + +/** prototype of a callback used when memory runs out */ typedef void *(*psMemExhaustedCallback)(size_t size); /*****************************************************************************/ -/** Fake for p_psAlloc */ -void *psAlloc(size_t size //!< Size required - ); -/** Fake for p_psRealloc */ -void *psRealloc(void *ptr, //!< Pointer to re-allocate - size_t size //!< Size required - ); -/** Fake for p_psFree */ -void psFree(void *ptr //!< Pointer to free - ); - -/** Memory allocation */ +/** Memory allocation. Underlying private function called by macro psAlloc. */ void *p_psAlloc(size_t size, //!< Size required const char *file, //!< File of call @@ -43,5 +38,5 @@ ); -/** Memory re-allocation */ +/** Memory re-allocation. Underlying private function called by macro psRealloc. */ void *p_psRealloc(void *ptr, //!< Pointer to re-allocate size_t size, //!< Size required @@ -50,5 +45,5 @@ ); -/** Free memory */ +/** Free memory. Underlying private function called by macro psFree. */ void p_psFree(void *ptr, //!< Pointer to free const char *file, //!< File of call @@ -56,16 +51,20 @@ ); -/** psAlloc sends file and line number to p_psAlloc */ +/** Memory allocation. psAlloc sends file and line number to p_psAlloc. */ #define psAlloc(size) p_psAlloc(size, __FILE__, __LINE__) -/** psRealloc sends file and line number to p_psRealloc */ + +/** Memory re-allocation. psRealloc sends file and line number to p_psRealloc. */ #define psRealloc(ptr, size) p_psRealloc(ptr, size, __FILE__, __LINE__) -/** psFree sends file and line number to p_psFree */ + +/** Free memory. psFree sends file and line number to p_psFree. */ #define psFree(size) p_psFree(size, __FILE__, __LINE__) -/* - * Ensure that any program using malloc/realloc/free will fail to compile - */ +/** prevent the use of 'malloc'. malloc is re-defined to throw an error in the C preprocessor */ #define malloc(S) for + +/** prevent the use of 'realloc'. realloc is re-defined to throw an error in the C preprocessor */ #define realloc(P,S) for + +/** prevent the use of 'free'. free is re-defined to throw an error in the C preprocessor */ #define free(P) for @@ -112,3 +111,4 @@ long psMemSetAllocateID(long id); //!< set p_psMemAllocateID to id long psMemSetFreeID(long id); //!< set p_psMemFreeID to id + #endif Index: /trunk/archive/pslib/include/psMetaData.h =================================================================== --- /trunk/archive/pslib/include/psMetaData.h (revision 246) +++ /trunk/archive/pslib/include/psMetaData.h (revision 247) @@ -2,9 +2,10 @@ #define PS_META_DATA_H 1 -#include "psImages.h" // for psImage -#include "psAstrom.h" // for psAstrom -/* - * Possible types of metadata. +/** \file psMetaData.h + * \brief Metadata handling structures and functions + * \ingroup AstroGroup */ + +/** Possible types of metadata. */ typedef enum { // type of val is: PS_META_ITEM_SET = 0, // NULL; metadata is in psMetaDataType.items @@ -20,4 +21,5 @@ } psMetaDataType; +/** Metadata flags (not exclusive with psMetaDataType). */ typedef enum { PS_META_TYPE_MASK = 0xffff, // the type enum must fit in this mask @@ -26,10 +28,7 @@ } psMetaDataFlags; -/* - * A struct to define a single item of metadata - */ +/** A struct to define a single item of metadata */ typedef struct { const int id; // unique ID for this item - char *restrict name; // Name of item psMetaDataType type; // type of this item @@ -44,7 +43,5 @@ } psMetaDataItem; -/* - * A set of metadata - */ +/** A set of metadata */ typedef struct { psDlist *restrict list; // list of psMetaDataItem @@ -52,8 +49,5 @@ } psMetaDataSet; -/*****************************************************************************/ -/* - * Constructors and destructors - */ +/** Constructor */ psMetaDataItem *psMetaDataItemAlloc( int typeFlags, // type of this piece of metadata + flags @@ -65,13 +59,15 @@ ...); // possible arguments for name format +/** Destructor */ void psMetaDataItemFree(psMetaDataItem *ms); // piece of metadata to destroy +/** Constructor */ psMetaDataSet *psMetaDataSetAlloc(void); // make a new set of metadata + +/** Destructor */ void psMetaDataSetFree(psMetaDataSet *ms); // destroy a set of metadata -/*****************************************************************************/ -/* - * Utilities - */ +/**** Utilities **********************************************************************/ + psMetaDataItem *psMetaDataAppend(psMetaDataSet *restrict ms, psMetaDataItem *restrict item); psMetaDataItem *psMetaDataRemove(psMetaDataSet *restrict ms, const char *restrict key); Index: /trunk/archive/pslib/include/psMinimize.h =================================================================== --- /trunk/archive/pslib/include/psMinimize.h (revision 246) +++ /trunk/archive/pslib/include/psMinimize.h (revision 247) @@ -1,4 +1,4 @@ -#if !defined(PS_MINIMISE_H) -#define PS_MINIMISE_H +#if !defined(PS_MINIMIZE_H) +#define PS_MINIMIZE_H /** \file psMinimize.h @@ -7,16 +7,14 @@ */ -/* Minimisation */ - -/** Minimise a particular function */ +/** Minimize a particular function */ psFloatArray * -psMinimise(float (*myFunction)(const psFloatArray *restrict), //!< Function to minimise +psMinimize(float (*myFunction)(const psFloatArray *restrict), //!< Function to minimize psFloatArray *restrict initialGuess //!< Initial guess ); -/** Minimise chi^2 for input data */ +/** Minimize chi^2 for input data */ psFloatArray * -psMinimiseChi2(float (*evalModel)(const psFloatArray *restrict, +psMinimizeChi2(float (*evalModel)(const psFloatArray *restrict, const psFloatArray *restrict), //!< Model to fit; receives domain and //!< parameters Index: /trunk/archive/pslib/include/psMisc.h =================================================================== --- /trunk/archive/pslib/include/psMisc.h (revision 246) +++ /trunk/archive/pslib/include/psMisc.h (revision 247) @@ -1,12 +1,9 @@ #if !defined(PS_MISC_H) #define PS_MISC_H -/** - * Concatenate two macro arguments + +/** \file psMisc.h + * \brief miscellaneous system utilities + * \ingroup SystemGroup */ -#define P_PS_CONCAT(A, B) A ## B //!< Expands to AB -#define PS_CONCAT(A, B) A ## B //!< Also Expands to AB -#define PS_CONCAT2(A, B) PS_CONCAT(A, B) //!< Also expands to AB -#define PS_CONCAT3(A, B, C) A ## B ## C //!< Expands to ABC -#define PS_CONCAT4(A, B, C, D) A ## B ## C ## D //!< Expands to ABCD #define PS_STRING(S) #S //!< converts argument to string @@ -27,3 +24,9 @@ ); +/** Magic values for errors */ +enum { + PS_NO_VALUE = -111, //!< Corresponding value not yet measured + PS_NO_ERROR = -222 //!< Corresponding value has no error +}; + #endif Index: /trunk/archive/pslib/include/psPosition.h =================================================================== --- /trunk/archive/pslib/include/psPosition.h (revision 246) +++ /trunk/archive/pslib/include/psPosition.h (revision 247) @@ -2,15 +2,8 @@ #define PS_POSITION_H -/* Include array declaration macros */ -#include "psArray.h" -#include "psObjects.h" - -/***********************************************************************************************************/ - -/** Magic values for errors */ -enum { - PS_NO_VALUE = -111, //!< Corresponding value not yet measured - PS_NO_ERROR = -222 //!< Corresponding value has no error -}; +/** \file psPosition.h + * \brief Definitions of objects in 2-D space + * \ingroup AstroGroup + */ /***********************************************************************************************************/ Index: /trunk/archive/pslib/include/psSort.h =================================================================== --- /trunk/archive/pslib/include/psSort.h (revision 246) +++ /trunk/archive/pslib/include/psSort.h (revision 247) @@ -2,7 +2,8 @@ #define PS_SORT_H -#include "psStdArrays.h" - -/* Sorting */ +/** \file psSort.h + * \brief general sorting operations + * \ingroup MathGroup + */ /** Sort an array. Inputs not restrict-ed to allow sort in place */ @@ -10,11 +11,11 @@ psSort(psFloatArray *out, //!< Sorted array to return. May be NULL const psFloatArray *myArray //!< Array to sort - ); + ); /** Sort an array, along with some other stuff. Returns an index array */ psIntArray * -psCoSort(psIntArray *restrict out; //!< Output index array (may be NULL) - const psFloatArray *restrict myArray //!< Array to sort - ); +psSortIndex(psIntArray *restrict out; //!< Output index array (may be NULL) + const psFloatArray *restrict myArray //!< Array to sort + ); #endif Index: /trunk/archive/pslib/include/psStats.h =================================================================== --- /trunk/archive/pslib/include/psStats.h (revision 246) +++ /trunk/archive/pslib/include/psStats.h (revision 247) @@ -2,7 +2,10 @@ #define PS_STATS_H -/* Include standard arrays */ -#include "psStdArrays.h" +/** \file psStats.h + * \brief basic statistical operations + * \ingroup MathGroup + */ +/** statistics which may be calculated */ typedef enum { PS_STAT_SAMPLE_MEAN = 0x000001, @@ -73,10 +76,10 @@ /** Histograms */ typedef struct { - const psFloatArray *restrict lower, *restrict upper; //!< Lower and upper bounds for the bins + const psFloatArray *restrict lower; //!< Lower bounds for the bins + const psFloatArray *restrict upper; //!< Upper bounds for the bins psIntArray *nums; //!< Number in each of the bins const float minVal, maxVal; //!< Minimum and maximum values int minNum, maxNum; //!< Number below the minimum and above the maximum } psHistogram; - /** Constructor */ Index: /trunk/archive/pslib/include/psStdArrays.h =================================================================== --- /trunk/archive/pslib/include/psStdArrays.h (revision 246) +++ /trunk/archive/pslib/include/psStdArrays.h (revision 247) @@ -2,8 +2,8 @@ #define PS_TYPES_H -#include -#include -#include "psArray.h" - +/** \file psStdArrays.h + * \brief Support for basic flat arrays + * \ingroup DataGroup + */ /** Types of the elements of vectors, matrices, etc. */ @@ -189,3 +189,28 @@ /************************************************************************************************************/ +/*****************************************************************************/ +/** Array of pointers to void. + * psVoidPtrArray is special, as it needs to have a destructor that + * accepts a destructor for the array elements + */ +typedef struct { + int n; //!< Number of elements in use + int size; //!< Number of total elements + void **arr; //!< The elements +} psVoidPtrArray; + +/** Constructor */ +psVoidPtrArray *psVoidPtrArrayAlloc(int n, //!< Number of elements to use + int s //!< Total number of elements + ); +/** Reallocate */ +psVoidPtrArray *psVoidPtrArrayRealloc(psVoidPtrArray *arr, //!< Array to reallocate + int n //!< Number of elements + ); +/** Destructor */ +void psVoidPtrArrayFree(psVoidPtrArray *arr, //!< array to destroy + void (*elemFree)(void *) //!< destructor for array data + ); + + #endif Index: /trunk/archive/pslib/include/psTrace.h =================================================================== --- /trunk/archive/pslib/include/psTrace.h (revision 246) +++ /trunk/archive/pslib/include/psTrace.h (revision 247) @@ -2,5 +2,11 @@ #define PS_TRACE_H 1 +/** \file psTrace.h + * \brief basic run-time trace facilities + * \ingroup SystemGroup + */ + //#define PS_NTRACE 1 //!< to turn off all tracing + #if defined(PS_NTRACE) # define psTrace(facil, level, ...) /* do nothing */ @@ -11,14 +17,17 @@ /** Send a trace message */ -void p_psTrace(const char *facil, int level, ...); +void p_psTrace(const char *facil, //!< facilty of interest + int level, //!< desired trace level + ... //!< trace message arguments +); /** Set trace level */ int psSetTraceLevel(const char *facil, //!< facilty of interest int level //!< desired trace level - ); +); /** Get the trace level */ int psGetTraceLevel(const char *name //!< facilty of interest - ); +); /** turn off all tracing, and free trace's allocated memory */