Index: /trunk/doc/pslib/psLibSDRS.tex
===================================================================
--- /trunk/doc/pslib/psLibSDRS.tex	(revision 295)
+++ /trunk/doc/pslib/psLibSDRS.tex	(revision 296)
@@ -1,2 +1,3 @@
+%%% $Id: psLibSDRS.tex,v 1.9 2004-03-24 03:39:01 price Exp $
 \documentclass[panstarrs]{panstarrs}
 %\documentclass[panstarrs]{panstarrs}
@@ -33,9 +34,4 @@
 \pagenumbering{arabic}
 
-%Here's a reference to another document:
-%\href{file:utils#psDlist}{utils.pdf}; the \code{#psDlist} points to
-%\CODE|\hlabel{psDlist}| in the file \file{utils.tex} (this is like
-%a regular \code{\label}, but defines the hyperlink too).
-
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -83,7 +79,4 @@
 described here.
 
-All of the memory management APIs should be provided in a header file
-\file{psMemory.h} which is included by \file{psUtils.h}.
-
 \subsubsection{Rationale}
 
@@ -146,11 +139,12 @@
 in the following struct definition:
 \begin{verbatim}
-  typedef struct {
-      const unsigned long id;           // a unique ID for this allocation
-      const char *file;                 // set from __FILE__ in e.g. p_psAlloc
-      const int lineno;                 // set from __LINE__ in e.g. p_psAlloc
-      int refcntr;                      // how many times pointer is referenced
-      const void *magic;                // initialised to P_PS_MEMMAGIC
-  } psMemBlock;
+typedef struct {
+    const void *magic0;			//!< initialised to p_psMEMMAGIC
+    const unsigned long id;		//!< a unique ID for this allocation
+    const char *file;			//!< set from __FILE__ in e.g. p_psAlloc
+    const int lineno;			//!< set from __LINE__ in e.g. p_psAlloc
+    int refCounter;			//!< how many times pointer is referenced
+    const void *magic;			//!< initialised to p_psMEMMAGIC
+} psMemBlock;
 \end{verbatim}
 
@@ -161,28 +155,36 @@
 \paragraph{APIs for using Memory Allocation Functions}
 
-\begin{table}
-\begin{verbatim}
-void *psAlloc(size_t size);
-void *psRealloc(void *ptr, size_t size);
-void psFree(void *ptr);
-
-void *p_psAlloc(size_t size, const char *file, int lineno);
-void *p_psRealloc(void *ptr, size_t size, const char *file, int lineno);
-void p_psFree(void *ptr, const char *file, int lineno);
-
+The types and function prototypes for the part of the memory API
+concerned with allocating and freeing memory are shown below.
+
+\begin{verbatim}
+/// Memory allocation. Underlying private function called by macro psAlloc. 
+void *p_psAlloc(size_t size,		//!< Size required
+		const char *file,	//!< File of call
+		int lineno		//!< Line number of call
+		);
+
+/// Memory re-allocation.  Underlying private function called by macro psRealloc. 
+void *p_psRealloc(void *ptr,		//!< Pointer to re-allocate
+		  size_t size,		//!< Size required
+		  const char *file,	//!< File of call
+		  int lineno		//!< Line number of call
+		  );
+
+/// Free memory.  Underlying private function called by macro psFree. 
+void p_psFree(void *ptr,		//!< Pointer to free
+	      const char *file,		//!< File of call
+	      int lineno		//!< Line number of call
+	      );
+
+/// Memory allocation. psAlloc sends file and line number to p_psAlloc. 
 #define psAlloc(size) p_psAlloc(size, __FILE__, __LINE__)
+
+/// Memory re-allocation.  psRealloc sends file and line number to p_psRealloc. 
 #define psRealloc(ptr, size) p_psRealloc(ptr, size, __FILE__, __LINE__)
+
+/// Free memory.  psFree sends file and line number to p_psFree. 
 #define psFree(size) p_psFree(size, __FILE__, __LINE__)
 \end{verbatim}
-\begin{caption}{The APIs required to use the \PS{} memory allocation routines}
-  \hlabel{tabUsageAPI}
-  The APIs required to use the \PS{} memory allocation routines, and as
-  provided by \file{psMemory.h}.
-\end{caption}
-\end{table}
-
-The types and function prototypes for the part of the memory API
-concerned with allocating and freeing memory are given in table
-\ref{tabUsageAPI}.
 
 N.b.
@@ -204,8 +206,9 @@
   
 \item
-  The file \file{psMemory.h} shall take steps to ensure that
-  code calling the functions \code{malloc}, \code{calloc}, \code{realloc},
-  or \code{free} shall not compile (\eg{} \code{#define malloc(S) for})
-  unless the symbol \code{PS_ALLOC_MALLOC} is defined.
+  The header file (\file{psMemory.h}) shall take steps to ensure that
+  code calling the functions \code{malloc}, \code{calloc},
+  \code{realloc}, or \code{free} shall not compile (\eg{}
+  \code{#define malloc(S) for}) unless the symbol
+  \code{PS_ALLOC_MALLOC} is defined.
 
 \item
@@ -245,38 +248,54 @@
 \hlabel{secMemAdvanced}
 
+The types and function prototypes for this part of the memory API
+are shown below.
+
 \begin{table}
 \begin{verbatim}
+/// 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);
 
-psMemProblemCallback psMemProblemSetCB(psMemProblemCallback func);
-psMemExhaustedCallback psMemExhaustedSetCB(psMemExhaustedCallback func);
-
-psMemCallback psMemAllocateSetCB(psMemCallback func);
-psMemCallback psMemFreeSetCB(psMemCallback func);
-
-int psMemGetId(void);                   // get next memory ID
-
-long psMemSetAllocateID(long id);       // set p_psMemAllocateID to id
-long psMemSetFreeID(long id);           // set p_psMemFreeID to id
-
-int psMemCheckLeaks(
-    int id0,                            // don't list blocks with id < id0
-    psMemBlock ***arr,                  // pointer to array of pointers to
-                                        //leaked blocks, or NULL
-    FILE *fd);                          // print list of leaks to fd (or NULL)
-int psMemCheckCorruption(int abort_on_error);
-\end{verbatim}
-\begin{caption}{The APIs required to use the \PS{} memory allocation routines}
-  \hlabel{tabCallbackAPI}
-  The APIs required to use the callback and tracing facilities
-  in \PS{} memory allocation routines, as defined in \file{psMemory.h}.
-\end{caption}
-\end{table}
-
-The types and function prototypes for this part of the memory API
-are given in table \ref{tabCallbackAPI}.
+/// Set callback for problems 
+psMemProblemCallback psMemProblemSetCB(psMemProblemCallback func //!< Function to run
+				       );
+
+/// Set callback for out-of-memory 
+psMemExhaustedCallback psMemExhaustedSetCB(psMemExhaustedCallback func //!< Function to run
+					   );
+
+/// Set call back for when a particular memory block is allocated 
+psMemCallback psMemAllocateSetCB(psMemCallback func //!< Function to run
+				 );
+
+/// Set call back for when a particular memory block is freed 
+psMemCallback psMemFreeSetCB(psMemCallback func
+			     );
+
+/// get next memory ID 
+int psMemGetId(void);
+
+/// set p_psMemAllocateID to id 
+long psMemSetAllocateID(long id		//!< ID to set
+			);
+
+/// set p_psMemFreeID to id 
+long psMemSetFreeID(long id		//!< ID to set
+		    );
+
+/// Check for memory leaks 
+int psMemCheckLeaks(int id0,		//!< don't list blocks with id < id0
+		    psMemBlock ***arr,	//!< pointer to array of pointers to leaked blocks, or NULL
+		    FILE *fd		//!< print list of leaks to fd (or NULL)
+		    );
+/// Check for memory corruption 
+int psMemCheckCorruption(int abort_on_error //!< Abort on detecting corruption?
+			 );
+\end{verbatim}
 
 \paragraph{Callback Routines}
@@ -381,7 +400,15 @@
 The API for this field is:
 \begin{verbatim}
-int psMemGetRefCounter(void *vptr);        // return refcounter
-void *psMemIncrRefCounter(void *vptr);     // increment refcounter and return vptr
-void *psMemDecrRefCounter(void *vptr);     // decrement refcounter and return vptr
+/// Return reference counter 
+int psMemGetRefCounter(void *vptr	//!< Pointer to get refCounter for
+		       );
+
+/// Increment reference counter and return the pointer 
+void *psMemIncrRefCounter(void *vptr	//!< Pointer to increment refCounter, and return
+			  );
+
+/// Decrement reference counter and return the pointer 
+void *psMemDecrRefCounter(void *vptr	//!< Pointer to decrement refCounter, and return
+			  );
 \end{verbatim}
 
@@ -391,5 +418,9 @@
 \subsubsubsection{Rationale}
 
-\begin{table}
+The \code{psMemBlock.refcounter} is clearly useful for detecting
+attempts to free memory that is already free.  A more complex
+application is for allowing pointers to complex data-objects (e.g.\
+images) to appear in more than one data structure simultaneously:
+
 \begin{verbatim}
 typedef struct {
@@ -417,13 +448,5 @@
 }
 \end{verbatim}
-\caption{An example of reference counting}
-\label{tabReferenceCounting}
-\end{table}
-
-The \code{psMemBlock.refcounter} is clearly useful for detecting
-attempts to free memory that is already free.  A more complex
-application is for allowing pointers to complex data-objects (e.g.
-images) to appear in more than one data structure simultaneously
-(see table \ref{tabReferenceCounting}).
+
 
 Because of the use of the \code{refcounter} field, we can safely put items of
@@ -456,6 +479,5 @@
 \hlabel{psTrace}
 
-\begin{table}
-  \begin{verbatim}
+\begin{verbatim}
 #if defined(PS_NTRACE)
 #  define psTrace(facil, level, ...) /* do nothing */
@@ -465,23 +487,25 @@
 #endif
 
-void p_psTrace(const char *facil, int level, ...);
-
-int psSetTraceLevel(const char *facil,  // facilty of interest
-                    int level);         // desired trace level
-int psGetTraceLevel(const char *name);  // facilty of interest
-
-void psTraceReset(void);                // turn off all tracing, and free trace's allocated memory
-
-void psPrintTraceLevels(void);          // print trace levels
-  \end{verbatim}
-  \begin{caption}{The public API for the trace facility
-      from \file{psTrace.h}.}
-    \hlabel{tabTraceAPI}
-  \end{caption}
-\end{table}
-
-The public API for the trace facility (table \ref{tabTraceAPI})
-should be provided in a header file \file{psTrace.h} which
-is included by \file{psUtils.h}.
+/// Send a trace message
+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 
+void psTraceReset(void);
+
+/// print trace levels 
+void psPrintTraceLevels(void);
+\end{verbatim}
 
 \begin{itemize}
@@ -489,5 +513,5 @@
     Logging is provided by the function \code{psTrace},
     which is actually a macro.  When the macro \code{PS_NTRACE}
-    is defined, all occurrences of  \code{psTrace} shall
+    is defined, all occurrences of \code{psTrace} shall
     be replaced by whitespace.
 
@@ -536,6 +560,6 @@
     \item
       There is no requirement that \code{psTrace} be usable from
-      within the functions that implement \file{psTrace.h}
-      or \file{psMemory.h} systems.
+      within the functions that implement the tracing or memory
+      management systems.
 
     \item
@@ -617,27 +641,24 @@
 \hlabel{psLogMsg}
 
-\begin{table}
-  \begin{verbatim}
-enum { PS_LOG_ABORT = 0, PS_LOG_ERROR, PS_LOG_WARN, PS_LOG_INFO };
-
-enum { PS_LOG_TO_STDERR, PS_LOG_TO_STDOUT };
-
-void psLogMsg(const char *name, int level, const char *fmt, ...);
-void p_psVLogMsg(const char *name, int level, const char *fmt, va_list ap);
-
-int psSetLogDestination(int dest);
-void psSetLogFormat(const char *fmt);
-
-int psSetLogLevel(int level);
-  \end{verbatim}
-  \begin{caption}{API for message logging}
-    \hlabel{tabLogMsgAPI}
-    The API for message logging.
-  \end{caption}
-\end{table}
-
-The public API for the logging facility (table \ref{tabLogMsgAPI})
-should be provided in a header file \file{psLogMsg.h} which
-is included by \file{psUtils.h}.
+\begin{verbatim}
+enum { PS_LOG_ABORT = 0, PS_LOG_ERROR, PS_LOG_WARN, PS_LOG_INFO }; //!< Status codes for log messages
+
+enum { PS_LOG_TO_STDERR, PS_LOG_TO_STDOUT }; //!< Destinations for log messages
+
+/// Logs a message
+void psLogMsg(const char *name, int level, const char *fmt, ...); 
+
+/// Logs a message from varargs
+void p_psVLogMsg(const char *name, int level, const char *fmt, va_list ap); 
+
+/// Sets the log destination 
+int psSetLogDestination(int dest);	
+
+/// Sets the log level
+int psSetLogLevel(int level);		
+
+/// sets the log format
+void psSetLogFormat(const char *fmt);	
+\end{verbatim}
 
 The function \code{psSetLogLevel} may be used to set the current
@@ -702,28 +723,30 @@
 \hlabel{psDlist}
 
-Pan-STARRS supports doubly linked lists through a type \code{psDlist}.
-The type is defined in the header file \file{psDlist.h}, and consists
-of the following definitions:
-
-\begin{verbatim}
+\PS{} supports doubly linked lists through a type \code{psDlist}.  The
+type consists of the following definitions:
+
+\begin{verbatim}
+/** Doubly-linked list element */
 typedef struct psDlistElem {
-    struct psDlistElem *prev;           // previous link in list
-    struct psDlistElem *next;           // next link in list
-    void *data;                         // real data item
+   struct psDlistElem *prev;		//!< previous link in list
+   struct psDlistElem *next;		//!< next link in list
+   void *data;				//!< real data item
 } psDlistElem;
 
+/** Doubly-linked list */
 typedef struct {
-    int n;                              // number of elements on list
-    psDlistElem *head;                  // first element on list (may be NULL)
-    psDlistElem *tail;                  // last element on list (may be NULL)
-    psDlistElem *iter;                  // iteration cursor; private
+   int n;				//!< number of elements on list
+   psDlistElem *head;			//!< first element on list (may be NULL)
+   psDlistElem *tail;			//!< last element on list (may be NULL)
+   psDlistElem *iter;			//!< iteration cursor
 } psDlist;
 
-enum {                                  // Special values of index into list
-    psDlistHead = 0,                    // at head
-    psDlistTail = -1,                   // at tail
-    psDlistUnknown = -2,                // unknown position
-    psDlistPrev = -3,                   // previous element
-    psDlistNext = -4                    // next element
+/** Special values of index into list */
+enum {
+   PS_DLIST_HEAD = 0,			//!< at head
+   PS_DLIST_TAIL = -1,			//!< at tail
+   PS_DLIST_UNKNOWN = -2,		//!< unknown position
+   PS_DLIST_PREV = -3,			//!< previous element
+   PS_DLIST_NEXT = -4			//!< next element
 };
 \end{verbatim}
@@ -732,38 +755,52 @@
 
 \begin{verbatim}
-psDlist *psDlistAlloc(void *data);        // initial data item; may be NULL
-
-void psDlistFree(psDlist *list,          // list to destroy
-                void (*elemFree)(void *)); // destructor for list data, or NULL
-
-/*
- * List maintainence functions
- */
-psDlist *psDlistAdd(psDlist *list,      // list to add to (may be NULL)
-                    void *data,         // data item to add
-                    int where);         // index, psDlistHead, or psDlistTail
-psDlist *psDlistAppend(psDlist *list,   // list to append to (may be NULL)
-                       void *data);     // data item to add
-void *psDlistRemove(psDlist *list,      // list to remove element from
-                    void *data,         // data item to remove
-                    int which);         // index of item, or psDlistUnknown,
-                                        // or psDlistNext, or psDlistPrev
-void *psDlistGet(const psDlist *list,   // list to retrieve element from
-                 int which);            // index of item, or psDlistNext,
-                                        // or psDlistPrev
-/*
- * Conversions to/from arrays
- */
-psVoidPtrArray *psDlistToArray(psDlist *dlist);
-psDlist *psArrayToDlist(psVoidPtrArray *arr);
-\end{verbatim}
-
-All data items placed onto lists (e.g. with \code{psDlistAdd})
-shall have their reference counters (section \ref{secMemRefcounter}) incremented.
-When elements
-are removed from a list with \code{psDlistRemove}, they shall
-have their reference counters decremented. The action of retrieving
-data from a list (with \code{psDlistGet}) shall not affect
-their reference counter.
+/** Constructor */
+psDlist *psDlistAlloc(void *data	//!< initial data item; may be NULL
+		      );
+
+/** Destructor */
+void psDlistFree(psDlist *list,		//!< list to destroy
+		void (*elemFree)(void *) //!< destructor for data on list
+		 );
+
+/**** List maintainence functions ****/
+
+/** Add to list */
+psDlist *psDlistAdd(psDlist *list,	//!< list to add to (may be NULL)
+		    void *data,		//!< data item to add
+		    int where		//!< index, PS_DLIST_HEAD, or PS_DLIST_TAIL
+		    );
+
+/** Append to a list */
+psDlist *psDlistAppend(psDlist *list,	//!< list to append to (may be NULL)
+		       void *data	//!< data item to add
+		       );
+
+/** Remove from a list */
+void *psDlistRemove(psDlist *list,	//!< list to remove element from
+		    void *data,		//!< data item to remove
+		    int which		//!< index of item, or PS_DLIST_UNKNOWN, or PS_DLIST_NEXT, or
+					//!< PS_DLIST_PREV
+		    );
+/** Retrieve from a list */
+void *psDlistGet(const psDlist *list,	//!< list to retrieve element from
+		 int which		//!< index of item, or PS_DLIST_NEXT, or PS_DLIST_PREV
+		 );
+
+/** Convert doubly-linked list to an array */
+psVoidPtrArray *psDlistToArray(psDlist *dlist //!< List to convert
+			       );
+
+/** Convert array to a doubly-linked list */
+psDlist *psArrayToDlist(psVoidPtrArray *arr //!< Array to convert
+			);
+\end{verbatim}
+
+All data items placed onto lists (e.g. with \code{psDlistAdd}) shall
+have their reference counters (section \ref{secMemRefcounter})
+incremented.  When elements are removed from a list with
+\code{psDlistRemove}, they shall have their reference counters
+decremented. The action of retrieving data from a list (with
+\code{psDlistGet}) shall not affect their reference counter.
 
 If \code{psDlistFree}'s argument \code{elemFree} is NULL, the
@@ -773,7 +810,22 @@
 Iteration over all elements of the list is provided by the functions:
 \begin{verbatim}
-void psDlistSetIterator(psDlist *list, int where, int which);
-void *psDlistGetNext(psDlist *list, int which);
-void *psDlistGetPrev(psDlist *list, int which);
+/** Set the iterator */
+void psDlistSetIterator(psDlist *list,	//!< list to retrieve element from
+			int where,	//!< index, PS_DLIST_HEAD, or PS_DLIST_TAIL
+			int which	//!< index of item, or PS_DLIST_UNKNOWN, or PS_DLIST_NEXT, or
+					//!< PS_DLIST_PREV
+			);
+
+/** Get next element */
+void *psDlistGetNext(psDlist *list,	//!< list to retrieve element from
+		     int which		//!< index of item, or PS_DLIST_UNKNOWN, or PS_DLIST_NEXT, or
+					//!< PS_DLIST_PREV
+		     );
+
+/** Get previous element */
+void *psDlistGetPrev(psDlist *list,	//!< list to retrieve element from
+		     int which		//!< index of item, or PS_DLIST_UNKNOWN, or PS_DLIST_NEXT, or
+					//!< PS_DLIST_PREV
+		     );
 \end{verbatim}
 in which the \code{where} argument must be \code{PS_DLIST_HEAD} or \code{PS_DLIST_TAIL},
@@ -815,6 +867,6 @@
 is the number of elements allocated ($s \ge n$).
 
-This type and functions may be declared and defined using two macros
-from \file{psArray.h}, \code{PS_DECLARE_ARRAY_TYPE(psType)} and
+This type and functions may be declared and defined using two macros,
+\code{PS_DECLARE_ARRAY_TYPE(psType)} and
 \code{PS_CREATE_ARRAY_TYPE(psType)}.  The former defines the
 \code{typedef} and declares the prototypes (and is thus suitable for
@@ -903,5 +955,5 @@
 \code{array}s.
 \begin{verbatim}
-#include "psUtils.h"
+#include "psLib.h"
 
 typedef struct {
@@ -960,36 +1012,40 @@
 \hlabel{psHash}
 
-\begin{table}
-  \begin{verbatim}
-typedef struct HashTable psHash;
-
-psHash *psHashAlloc(int nbucket);       // initial number of buckets
-void psHashFree(psHash *table,          // hash table to be freed
-               void (*itemFree)(void *item)); // how to free hashed data;
-                                        // or NULL
-
-void *psHashInsert(psHash *table,       // table to insert in
-                   const char *key,     // key to use
-                   void *data,          // data to insert
-                   void (*itemFree)(void *item)); // how to free hashed data;
-                                        // or NULL
-void *psHashLookup(psHash *table,       // table to lookup key in
-                   const char *key);    // key to lookup
-
-void *psHashRemove(psHash *table,       // table to lookup key in
-                   const char *key);    // key to lookup
-  \end{verbatim}
-  \begin{caption}{The public API for hash tables from \file{psHash.h}}
-    \hlabel{tabPsHash}
-  \end{caption}
-\end{table}
-
-The public API for the hash table (table \ref{tabPsHash})
-should be provided in a header file \file{psHash.h} which
-is included by \file{psUtils.h}.
+The public APIs for the hash table (table \ref{tabPsHash}) are shown below.
 \footnote{
   We choose not to use the posix function \code{hcreate},
   \code{hdestroy}, and \code{hsearch} as they only support
   a single hash table at any one time.}
+
+\begin{verbatim}
+typedef struct HashTable psHash;	///< Opaque type for a hash table
+
+/// Allocate hash buckets in table.
+psHash *psHashAlloc(int nbucket		///< initial number of buckets
+    );
+
+/// Free hash buckets from table.
+void psHashFree(psHash *table,		///< hash table to be freed
+		void (*itemFree)(void *item) ///< how to free hashed data; or NULL
+    );
+
+/// Insert entry into table.
+void *psHashInsert(psHash *table,	///< table to insert in
+		   const char *key,	///< key to use
+		   void *data,		///< data to insert
+		   void (*itemFree)(void *item) ///< how to free hashed data; or NULL
+    );
+
+/// Lookup key in table.
+void *psHashLookup(psHash *table,	///< table to lookup key in
+		   const char *key	///< key to lookup
+    );
+
+/// Remove key from table.
+void *psHashRemove(psHash *table,	///< table to lookup key in
+		   const char *key	///< key to lookup
+    );
+\end{verbatim}
+
 
 A hash table is an abstract type \code{psHash}.  The argument
@@ -1016,20 +1072,28 @@
 \subsection{Miscellaneous Utilities}
 
-\begin{table}
-  \begin{verbatim}
-#define PS_CONCAT(A, B) A ## B          // 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
-
+\begin{verbatim}
 #define PS_STRING(S) #S                 // converts argument S to string
     
-void psAbort(const char *name, const char *fmt, ...);
-void psError(const char *name, const char *fmt, ...);
-char *psStringCopy(const char *str);
-  \end{verbatim}
-  \begin{caption}{The utilities provided by \file{psMisc.h}}
-      \hlabel{psMisc}
-  \end{caption}
-\end{table}
+/// Prints an error message and aborts
+void psAbort(const char *name,		///< Category of code that caused the abort
+	     const char *fmt,		///< Format
+	     ...			///< Extra arguments to use format
+	     );
+
+/// Prints an error message and doesn't abort
+void psError(const char *name,		///< Category of code that caused the abort
+	     const char *fmt,		///< Format
+	     ...			///< Extra arguments to use format
+    );
+
+/// Allocates and returns a copy of a string
+char *psStringCopy(const char *str	///< string to copy
+    );
+
+/// Allocates nChar and returns a copy of the string or segment
+char *psStringNCopy(const char *str,	///< string to copy
+		    int nChar		//!< Number of characters (including \0 )
+    );
+\end{verbatim}
 
 \code{psAbort} shall call \code{psMsgLog} with a level of \code{PS_LOG_ABORT},
@@ -1141,5 +1205,5 @@
             char *operator,             ///< operator
             void *in2                   ///< second input
-);
+    );
 \end{verbatim}
 
@@ -1151,5 +1215,5 @@
            void *in,                    ///< input
            char *operator,              ///< operator
-);
+    );
 \end{verbatim}
 
@@ -1182,12 +1246,13 @@
 
 \begin{verbatim}
+/** private structure used to pass constant values into the math operators. */
 typedef struct {
-    psType type;
-    union {
-        int i;
-        float f;
-        double d;
-        complex float c;
-    }
+    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
+    } val;
 } p_psScalar;
 \end{verbatim}
@@ -1644,21 +1709,22 @@
 /// basic image data structure.
 typedef struct psImage {
-    psType type;                        ///< image data type and dimension
-    int nx, ny;                         ///< size of image 
-    int x0, y0;                         ///< data region relative to parent 
+    psType type; 			///< image data type and dimension
+    int nx, ny;				///< size of image 
+    int x0, y0;				///< data region relative to parent 
     union {
-        psF32 **rows;                   ///< == rows_f32 
-        psS8  **rows_s8;                ///< pointers to psS8 data 
-        psS16 **rows_s16;               ///< pointers to psS16 data 
-        psS32 **rows_s32;               ///< pointers to psS32 data 
-        psU8  **rows_u8;                ///< pointers to psU8 data 
-        psU16 **rows_u16;               ///< pointers to psU16 data 
-        psU32 **rows_u32;               ///< pointers to psU32 data 
-        psF32 **rows_f32;               ///< pointers to psF32 data 
-        psF64 **rows_f64;               ///< pointers to psF64 data 
+	psF32 **rows;		        ///< == rows_f32 
+	psS8  **rows_s8;		///< pointers to psS8 data 
+	psS16 **rows_s16;		///< pointers to psS16 data 
+	psS32 **rows_s32;		///< pointers to psS32 data 
+	psU8  **rows_u8;		///< pointers to psU8 data 
+	psU16 **rows_u16;		///< pointers to psU16 data 
+	psU32 **rows_u32;		///< pointers to psU32 data 
+	psF32 **rows_f32;		///< pointers to psF32 data 
+	psF64 **rows_f64;		///< pointers to psF64 data 
+	psComplex **rows_complex;	//!< pointers to psComplex data
     } rows;
-    struct psImage *parent;             ///< parent, if a subimage 
-    struct psImage *children;           ///< children of this region 
-    int Nchildren;                      ///< number of subimages 
+    psImage *parent;			///< parent, if a subimage 
+    int Nchildren;			///< number of subimages 
+    psImage *children;			///< children of this region; array of Nchildren pointers
 } psImage;
 \end{verbatim}
@@ -1695,10 +1761,13 @@
 outside of the parent image.
 \begin{verbatim}
+/// Create a subimage of the specified area.
 psImage *
-psImageSubset (psImage *image,          ///< parent image 
-               int nx,                  ///< subimage width (<= image.nx - x0)  
-               int ny,                  ///< subimage width (<= image.ny - y0)  
-               int x0,                  ///< subimage x-offset (0 <= x0 < nx)   
-               int y0)                  ///< subimage y-offset (0 <= y0 < ny)   
+psImageSubset(psImage *out,		//!< Subimage to return, or NULL
+	      const psImage *image,	///< parent image 
+	      int nx,			///< subimage width (<= image.nx - x0)  
+	      int ny,			///< subimage width (<= image.ny - y0)  
+	      int x0,			///< subimage x-offset (0 <= x0 < nx)   
+	      int y0			///< subimage y-offset (0 <= y0 < ny)   
+    );
 \end{verbatim}
 
@@ -1730,6 +1799,7 @@
 \begin{verbatim}
 psImage *
-psImageCopy (psImage *output,           ///< target structure for output image data
-             psImage *input)            ///< copy this image 
+psImageCopy(psImage *output, 		///< target structure for output image data
+	    const psImage *input	///< copy this image 
+    );
 \end{verbatim}
 
@@ -1744,11 +1814,13 @@
 \begin{verbatim}
 psFloatArray *
-psImageSlice (psImage *input,           ///< extract slice from this image
-              int x,                    ///< starting x coord of region to slice
-              int y,                    ///< starting y coord of region to slice
-              int nx,                   ///< width of region in x
-              int ny,                   ///< width of region in y
-              int direction,            ///< direction of vector along slice
-              psStats *stats)           ///< defines statistics used to find output values
+psImageSlice(psFloatArray *out,		//!< Vector to output, or NULL
+	     const psImage *input,	///< extract slice from this image
+	     int x, 			///< starting x coord of region to slice
+	     int y, 			///< starting y coord of region to slice
+	     int nx, 			///< width of region in x
+	     int ny, 			///< width of region in y
+	     int direction,		///< direction of vector along slice
+	     const psStats *stats	///< defines statistics used to find output values
+    );
 \end{verbatim}
 
@@ -1764,11 +1836,13 @@
 \begin{verbatim}
 psFloatArray *
-psImageCut (psImage *input,             ///< extract cut from this image
-            float xs,                   ///< starting x coord of cut
-            float ys,                   ///< starting y coord of cut
-            float xe,                   ///< ending x coord of cut
-            float ye,                   ///< ending y coord of cut
-            float dw,                   ///< width of cut
-            psStats *stats)             ///< defines statistics used to find output values
+psImageCut(psFloatArray *out,		//!< Vector to output, or NULL
+	   const psImage *input,	///< extract cut from this image
+	   float xs, 			///< starting x coord of cut
+	   float ys, 			///< starting y coord of cut
+	   float xe, 			///< ending x coord of cut
+	   float ye, 			///< ending y coord of cut
+	   float dw, 			///< width of cut
+	   const psStats *stats		///< defines statistics used to find output values
+    );
  \end{verbatim}
 
@@ -1783,19 +1857,13 @@
 \begin{verbatim}
 psFloatArray *
-psImageRadialCut (psImage *input,       ///< extract profile from this image
-                  float x,              ///< center x coord of annulii
-                  float y,              ///< center y coord of annulii
-                  float radius,         ///< outer radius of annulii
-                  float dr,             ///< radial step size of annulii
-                  psStats *stats)       ///< defines statistics used to find output values 
-\end{verbatim}
-
-%/// Extract a 2-d contour from an image at the given threshold.
-%\begin{verbatim}
-%psFloatArray *
-%psImageContour (psImage *input,        ///< create contour for this image
-%               float threshold,        ///< contour image at this threshold
-%               int binning)            ///< bin image by this value for contour calculation
-%\end{verbatim}
+psImageRadialCut(psFloatArray *out,	//!< Vector to output, or NULL
+		 const psImage *input,	///< extract profile from this image
+		 float x, 		///< center x coord of annulii
+		 float y, 		///< center y coord of annulii
+		 float radius,		///< outer radius of annulii
+		 float dr,		///< radial step size of annulii
+		 const psStats *stats	///< defines statistics used to find output values
+    );
+\end{verbatim}
 
 Rebin image to new scale.  A new image is constructed in which the
@@ -1808,7 +1876,9 @@
 \begin{verbatim}
 psImage *
-psImageRebin (psImage *input,           ///< rebin this image
-              float scale,              ///< rebinning scale: doutput = scale*dinput
-              psStats *stats)           ///< defines statistics used to find output values
+psImageRebin(psImage *out,		//!< Image to output, or NULL
+	     const psImage *input,	///< rebin this image
+	     float scale, 		///< rebinning scale: doutput = scale*dinput
+	     const psStats *stats	///< defines statistics used to find output values
+    );
 \end{verbatim}
 
@@ -1821,6 +1891,8 @@
 \begin{verbatim}
 psImage *
-psImageRotate (psImage *input,          ///< rotate this image
-               float angle)             ///< rotate by this amount (degrees)
+psImageRotate(psImage *out,		//!< Image to output, or NULL
+	      const psImage *input,	///< rotate this image
+	      float angle		///< rotate by this amount anti-clockwise (degrees)
+    );
 \end{verbatim}
 
@@ -1833,8 +1905,10 @@
 \begin{verbatim}
 psImage *
-psImageShift (psImage *input,           ///< shift this image
-              float dx,                 ///< shift by this amount in x
-              float dy,                 ///< shift by this amount in y
-              float exposed)            ///< set exposed pixels to this value
+psImageShift(psImage *out,		//!< Image to output, or NULL
+	     const psImage *input,	///< shift this image
+	     float dx,			///< shift by this amount in x
+	     float dy,			///< shift by this amount in y
+	     float exposed		///< set exposed pixels to this value
+    );
 \end{verbatim}
 
@@ -1844,7 +1918,9 @@
 \begin{verbatim}
 psImage *
-psImageRoll (psImage *input,            ///< roll this image
-             int dx,                    ///< roll this amount in x
-             int dy)                    ///< roll this amount in y
+psImageRoll(psImage *out,		//!< Image to output, or NULL
+	    const psImage *input,	///< roll this image
+	    int dx, 			///< roll this amount in x
+	    int dy			///< roll this amount in y
+    );
 \end{verbatim}
 
@@ -1853,6 +1929,7 @@
 \begin{verbatim}
 psStats *
-psImageGetStats (psImage *input,        ///< image (or subimage) to calculate stats
-                 psStats *stats)        ///< defines statistics to be calculated
+psImageGetStats(const psImage *input, 	///< image (or subimage) to calculate stats
+		psStats *stats		///< defines statistics to be calculated & target
+    );
 \end{verbatim}
 
@@ -1861,6 +1938,7 @@
 \begin{verbatim}
 psHistogram *
-psImageHistogram (psHistogram *hist,    ///< input histogram description & target
-                  psImage *input)       ///< determine histogram of this image
+psImageHistogram(psHistogram *hist,	///< input histogram description & target
+		 const psImage *input	///< determine histogram of this image
+    );
 \end{verbatim}
 
@@ -1870,6 +1948,7 @@
 \begin{verbatim}
 psPolynomial2D *
-psImageFitPolynomial (psImage *input,   ///< image to fit
-                      psPolynomial2D *coeffs) ///< coefficient structure carries in desired terms
+psImageFitPolynomial(const psImage *input, ///< image to fit
+		     psPolynomial2D *coeffs ///< coefficient structure carries in desired terms & target
+    );
 \end{verbatim}
 
@@ -1880,6 +1959,7 @@
 \begin{verbatim}
 int
-psImageEvalPolynomial (psImage *input,  ///< image to fit
-                       psPolynomial2D *coeffs) ///< coefficient structure carries in desired terms
+psImageEvalPolynomial(const psImage *input, ///< image to fit
+		      const psPolynomial2D *coeffs ///< coefficient structure carries in desired terms
+    );
 \end{verbatim}
 
@@ -1900,13 +1980,14 @@
 \begin{verbatim}
 psImage *
-psImageReadSection (psImage *output,    ///< place data in this structure for output 
-                    int x,              ///< starting x coord of region
-                    int y,              ///< starting y coord of region
-                    int nx,             ///< x size of region (-1 for full range)
-                    int ny,             ///< y size of region (-1 for full range)
-                    int z,              ///< plane of interest
-                    char *extname,      ///< MEF extension name ("PHU" for primary header)
-                    int extnum,         ///< MEF extension sequence number (-1 for PHU)
-                    char *filename)     ///< file to read data from
+psImageReadSection(psImage *output, 	///< place data in this structure for output 
+		   int x, 		///< starting x coord of region
+		   int y, 		///< starting y coord of region
+		   int nx, 		///< x size of region (-1 for full range)
+		   int ny, 		///< y size of region (-1 for full range)
+		   int z, 		///< plane of interest
+		   const char *extname,	///< MEF extension name ("PHU" for primary header)
+		   int extnum,		///< MEF extension number (-1 for "PHU", 0 : Nextend - 1)
+		   const char *filename	///< file to read data from
+    );
 \end{verbatim}
  
@@ -1916,12 +1997,14 @@
 \begin{verbatim}
 psImage *
-psImageFReadSection (psImage *output,   ///< place data in this structure for output 
-                     int x,             ///< starting x coord of region            
-                     int y,             ///< starting y coord of region            
-                     int dx,            ///< x size of region (-1 for full range)          
-                     int dy,            ///< y size of region (-1 for full range)          
-                     int z,             ///< plane of interest                     
-                     char *extname,     ///< MEF extension name ("PHU" for primary header)                         
-                     FILE *f)           ///< file descriptor to read data from             
+psImageFReadSection(psImage *output,	///< place data in this structure for output 
+		    int x,		///< starting x coord of region		   
+		    int y,		///< starting y coord of region		   
+		    int dx,		///< x size of region (-1 for full range)	   
+		    int dy,		///< y size of region (-1 for full range)	   
+		    int z,		///< plane of interest			   
+		    const char *extname, ///< MEF extension name ("PHU" for primary header)
+		    int extnum, 	///< MEF extension number (-1 for "PHU", 0 : Nextend - 1)
+		    FILE *f	///< file descriptor to read data from		   
+    );
 \end{verbatim}
 
@@ -1936,10 +2019,12 @@
 \begin{verbatim}
 psImage *
-psImageWriteSection (psImage *input,    ///< image to write out
-                     int x,             ///< starting x coord of region            
-                     int y,             ///< starting y coord of region            
-                     int z,             ///< plane of interest                     
-                     char *extname,     ///< MEF extension name ("PHU" for primary header)
-                     char *filename)    ///< file to write data to                 
+psImageWriteSection(psImage *input,    ///< image to write out
+		    int x, 		///< starting x coord of region		   
+		    int y, 		///< starting y coord of region		   
+		    int z, 		///< plane of interest			   
+		    const char *extname, ///< MEF extension name ("PHU" for primary header)
+		    int extnum, 	///< MEF extension number (-1 for "PHU", 0 : Nextend - 1)
+		    const char *filename ///< file to write data to		   
+    );
 \end{verbatim}
 
@@ -1947,10 +2032,12 @@
 \begin{verbatim}
 psImage *
-psImageFWriteSection(psImage *input,    ///< image to write out
-                     int x,             ///< starting x coord of region            
-                     int y,             ///< starting y coord of region            
-                     int z,             ///< plane of interest                     
-                     char *extname,     ///< MEF extension name                    
-                     FILE *f)           ///< file descriptor to write data to              
+psImageFWriteSection(psImage *input,	///< image to write out
+		     int x, 		///< starting x coord of region		   
+		     int y, 		///< starting y coord of region		   
+		     int z, 		///< plane of interest			   
+		     const char *extname, ///< MEF extension name			   
+		     int extnum, 	///< MEF extension number (-1 for "PHU", 0 : Nextend - 1)
+		     FILE *f		///< file descriptor to write data to		   
+    );
 \end{verbatim}
 
@@ -1961,9 +2048,10 @@
 return an error.  
 \begin{verbatim}
-struct psMetadata *
-psImageReadHeader(struct psMetadata *output,    ///< read data to this structure
-                  char *extname,        ///< MEF extension name ("PHU" for primary header)
-                  int extnum,           ///< MEF extension number (-1 for "PHU", 0 : Nextend - 1)
-                  char *filename)       ///< file to read from
+psMetadata *
+psImageReadHeader(psMetadata *output,	///< read data to this structure
+		  const char *extname, 	///< MEF extension name ("PHU" for primary header)
+		  int extnum,		///< MEF extension number (-1 for "PHU", 0 : Nextend - 1)
+		  const char *filename	///< file to read from
+    );
 \end{verbatim}
 
@@ -1971,9 +2059,10 @@
 structure.  
 \begin{verbatim}
-struct psMetadata *
-psImageFReadHeader (struct psMetadata *output, ///< read data to this structure
-                   char *extname,       ///< MEF extension name ("PHU" for primary header)
-                   int extnum,          ///< MEF extension number (-1 for "PHU", 0 : Nextend - 1)
-                   FILE *f)             ///< file descriptor to read from
+psMetadata *
+psImageFReadHeader(psMetadata *output, ///< read data to this structure
+		   const char *extname,	///< MEF extension name ("PHU" for primary header)
+		   int extnum,		///< MEF extension number (-1 for "PHU", 0 : Nextend - 1)
+		   FILE *f      	///< file descriptor to read from
+    );
 \end{verbatim}
 
@@ -1982,6 +2071,8 @@
 \begin{verbatim}
 psImage *
-psImageFFT (psImage *input,             ///< image to FFT
-            int direction)              ///< FFT direction 
+psImageFFT(psImage *output,		//!< Output image
+	   const psImage *input,	///< image to FFT
+	   int direction		///< FFT direction 
+    );
 \end{verbatim}
 
@@ -1991,9 +2082,10 @@
 \begin{verbatim}
 int
-psImageClip (psImage *input,            ///< clip this image
-             float min,                 ///< clip pixels with values < min
-             float vmin,                ///< set min-clipped pixels to vmin
-             float max,                 ///< clip pixels with values > max
-             float vmax)                ///< set max-clipped pixels to vmax
+psImageClip(psImage *input, 		///< clip this image
+	    float min,			///< clip pixels with values < min
+	    float vmin, 		///< set min-clipped pixels to vmin
+	    float max,			///< clip pixels with values > max
+	    float vmax			///< set max-clipped pixels to vmax
+    );
 \end{verbatim}
 
@@ -2003,6 +2095,7 @@
 \begin{verbatim}
 int
-psImageClipNaN (psImage *input,         ///< clip this image
-                float value)            ///< set nan pixels to this value
+psImageClipNaN(psImage *input,		///< clip this image & target
+	       float value		///< set nan pixels to this value
+    );
 \end{verbatim}
 
@@ -2016,10 +2109,13 @@
 \begin{verbatim}
 int 
-psImageOverlaySection (psImage *image,          ///< input image 
-                psImage *overlay,       ///< image to overlay 
-                int x0,                 ///< x offset of overlay subimage 
-                int y0,                 ///< y offset of overlay subimage 
-                char *operator)         ///< overlay operation 
-\end{verbatim}
+psImageOverlaySection(psImage *image,	///< input image & target
+		      const psImage *overlay, ///< image to overlay 
+		      int x0,		///< x offset of overlay subimage 
+		      int y0,		///< y offset of overlay subimage 
+		      const char *operator ///< overlay operation 
+    );
+\end{verbatim}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \subsection{Astrometry}
@@ -2172,10 +2268,11 @@
 typedef struct {
     int nCells;                         ///< Number of Cells assigned
-    struct psCell *cells;               ///< Cells in the Chip
-
-    psMetaDataSet *md;                  ///< Chip-level metadata
+    psCell *cells;			///< Cells in the Chip
+
+    psMetaDataSet *md;			///< Chip-level metadata
     psCoordXform *chipToFPA;            ///< Transformations from chip coordinates to FPA coordinates
-
-    struct psFPA *parentFPA;            ///< FPA which contains this chip
+    psCoordXform *FPAtoChip;		//!< Transformations from FPA coordinates to chip
+
+    struct psFPA *parentFPA;		///< FPA which contains this chip
 } psChip;
 \end{verbatim}
@@ -2207,10 +2304,10 @@
     int nChips;                         ///< Number of Cells assigned
     int nAlloc;                         ///< Number of Cells available
-    struct psChip *chips;               ///< Chips in the Focal Plane Array
-
-    psMetaDataSet *md;                  ///< FPA-level metadata 
-    psDistortion *TPtoFP;               ///< Transformation term from 
-    psDistortion *FPtoTP;               ///< Transformation term from 
-    psFixedPattern *pattern;            //!< Fixed pattern residual offsets
+    psChip *chips;			///< Chips in the Focal Plane Array
+
+    psMetaDataSet *md;			///< FPA-level metadata 
+    psDistortion *TPtoFP;		///< Transformation term from 
+    psDistortion *FPtoTP;		///< Transformation term from 
+    psFixedPattern *pattern;		//!< Fixed pattern residual offsets
     psExposure *exp;                    ///< information about this exposure
     psPhotSystem colorPlus, colorMinus; ///< Colour reference
@@ -2230,5 +2327,5 @@
 
 \begin{verbatim}
-/** Information needed (by SLALIB) to convert Apparent to Observed Position */
+/** Information needed (by SLALib) to convert Apparent to Observed Position */
 typedef struct {
     double latitude;                    ///< geodetic latitude (radians)
@@ -2341,7 +2438,8 @@
 /** returns Chip in FPA which contains the given FPA coordinate */
 psChip *
-psChipInFPA (psFPA *fpa,                ///< FPA description
-             psCoord *coord             ///< coordinate in FPA
-             );
+psChipInFPA (psChip *out,		//!< Chip to return, or NULL
+	     const psFPA *fpa, 		///< FPA description
+	     const psCoord *coord	///< coordinate in FPA
+	     );
 \end{verbatim}
 
@@ -2349,7 +2447,8 @@
 /** returns Cell in Chip which contains the given chip coordinate */
 psCell *
-psCellInChip (psChip *chip,             ///< chip description
-              psCoord *coord            ///< coordinate in chip
-              );
+psCellInChip(psCell *out,		//!< Cell to return, or NULL
+	     const psChip *chip,	///< chip description
+	     const psCoord *coord	///< coordinate in chip
+	     );
 \end{verbatim}
 
@@ -2361,8 +2460,8 @@
 /** Return the cell in FPA which contains the given FPA coordinates */
 psCell *
-psCellInFPA(psCell *out,                //!< Cell to return, or NULL
-            psFPA *fpa,                 //!< FPA description
-            psCoord *coord              //!< Coordinate in FPA
-            );
+psCellInFPA(psCell *out,		//!< Cell to return, or NULL
+	    const psFPA *fpa,		//!< FPA description
+	    const psCoord *coord	//!< Coordinate in FPA
+	    );
 \end{verbatim}
 
@@ -2398,31 +2497,4 @@
 
 \begin{verbatim}
-/** returns Chip in FPA which contains the given FPA coordinate */
-psChip *
-psChipInFPA (psChip *out,               //!< Chip to return, or NULL
-             psFPA *fpa,                ///< FPA description
-             psCoord *coord             ///< coordinate in FPA
-             );
-\end{verbatim}
-
-\begin{verbatim}
-/** returns Cell in Chip which contains the given chip coordinate */
-psCell *
-psCellInChip(psCell *out,               //!< Cell to return, or NULL
-             psChip *chip,              ///< chip description
-             psCoord *coord             ///< coordinate in chip
-             );
-\end{verbatim}
-
-\begin{verbatim}
-/** Return the cell in FPA which contains the given FPA coordinates */
-psCell *
-psCellInFPA(psCell *out,                //!< Cell to return, or NULL
-            psFPA *fpa,                 //!< FPA description
-            psCoord *coord              //!< Coordinate in FPA
-            );
-\end{verbatim}
-
-\begin{verbatim}
 /** Convert (RA,Dec) to cell and cell coordinates */
 psCoord *
@@ -2436,8 +2508,8 @@
 /** Convert cell and cell coordinate to (RA,Dec) */
 psCoord *
-psCoordCellToSky(psCoord *out,          //!< Coordinates to return, or NULL
-                 const psCell *cell,    //!< Cell to get coordinates for
-                 psCoord *coord         //!< cell coordinates to transform
-                 );
+psCoordCellToSky(psCoord *out,		//!< Coordinates to return, or NULL
+		 const psCell *cell,	//!< Cell to get coordinates for
+		 const psCoord *coord	//!< cell coordinates to transform
+		 );
 \end{verbatim}
 
@@ -2445,8 +2517,8 @@
 /** Quick and dirty cell to (RA,Dec) --- employs cellToSky transformation */
 psCoord *
-psCoordCellToSkyQuick(psCoord *out,     //!< Coordinates to return, or NULL
-                      const psCell *cell, //!< Cell description
-                      psCoord *coord    //!< cell coordinates to transform
-                      );
+psCoordCellToSkyQuick(psCoord *out,	//!< Coordinates to return, or NULL
+		      const psCell *cell, //!< Cell description
+		      const psCoord *coord //!< cell coordinates to transform
+		      );
 \end{verbatim}
 
@@ -2454,8 +2526,8 @@
 /** Convert (RA,Dec) to tangent plane coords */
 psCoord *
-psCoordSkyToTP(psCoord *out,            //!< Coordinates to return, or NULL
-               psexposure *exp,         //!< Exposure description
-               psCoord *coord           //!< input Sky coordinate
-               );
+psCoordSkyToTP(psCoord *out,		//!< Coordinates to return, or NULL
+	       const psExposure *exp,	//!< Exposure description
+	       const psCoord *coord	//!< input Sky coordinate
+	       );
 \end{verbatim}
 
@@ -2463,8 +2535,8 @@
 /** Convert tangent plane coords to focal plane coordinates */
 psCoord *
-psCoordTPtoFPA(psCoord *out,            //!< Coordinates to return, or NULL
-               const psFPA *fpa,        //!< FPA description
-               psCoord *coord           //!< input TP coordinate
-               );
+psCoordTPtoFPA(psCoord *out,		//!< Coordinates to return, or NULL
+	       const psFPA *fpa,	//!< FPA description
+	       const psCoord *coord	//!< input TP coordinate
+	       );
 \end{verbatim}
 
@@ -2472,9 +2544,8 @@
 /** converts the specified FPA coord to the coord on the given Chip */
 psCoord *
-psCoordFPAtoChip (psCoord *out,         //!< Coordinates to return, or NULL
-                  psFPA *fpa,           ///< FPA description
-                  psChip *chip,         ///< Chip of interest
-                  psCoord *coord        ///< input FPA coordinate
-                  ); 
+psCoordFPAtoChip (psCoord *out,		//!< Coordinates to return, or NULL
+		  const psChip *chip,	///< Chip of interest
+		  const psCoord *coord	///< input FPA coordinate
+		  ); 
 \end{verbatim}
 
@@ -2482,9 +2553,8 @@
 /** converts the specified Chip coord to the coord on the given Cell */
 psCoord *
-psCoordChiptoCell (psCoord *out,        //!< Coordinates to return, or NULL
-                   psChip *chip,        ///< Chip description
-                   psCell *cell,        ///< Cell of interest
-                   psCoord *coord       ///< input Chip coordinate
-                   );
+psCoordChiptoCell (psCoord *out,	//!< Coordinates to return, or NULL
+		   const psCell *cell, 	///< Cell of interest
+		   const psCoord *coord	///< input Chip coordinate
+		   );
 \end{verbatim}
 
@@ -2492,8 +2562,8 @@
 /** converts the specified Cell coord to the coord on the parent Chip */
 psCoord *
-psCoordCelltoChip (psCoord *out,        //!< Coordinates to return, or NULL
-                   psCell *cell,        ///< Cell description
-                   psCoord *coord       ///< input Cell coordinate
-                   );
+psCoordCelltoChip (psCoord *out,	//!< Coordinates to return, or NULL
+		   const psCell *cell, 	///< Cell description
+		   const psCoord *coord	///< input Cell coordinate
+		   );
 \end{verbatim}
 
@@ -2501,8 +2571,8 @@
 /** converts the specified Chip coord to the coord on the parent FPA */
 psCoord *
-psCoordChiptoFPA (psCoord *out,         //!< Coordinates to return, or NULL
-                  psChip *chip,         ///< Chip description
-                  psCoord *coord        ///< input Chip coordinate
-                  );
+psCoordChiptoFPA (psCoord *out,		//!< Coordinates to return, or NULL
+		  const psChip *chip, 	///< Chip description
+		  const psCoord *coord	///< input Chip coordinate
+		  );
 \end{verbatim}
 
@@ -2510,8 +2580,8 @@
 /** Convert focal plane coords to tangent plane coordinates */
 psCoord *
-psCoordFPAToTP(psCoord *out,            //!< Coordinates to return, or NULL
-               psFPA *fpa,              //!< FPA description
-               psCoord *coord           //!< input FPA coordinate
-               );
+psCoordFPAToTP(psCoord *out,		//!< Coordinates to return, or NULL
+	       const psFPA *fpa,	//!< FPA description
+	       const psCoord *coord	//!< input FPA coordinate
+	       );
 \end{verbatim}
 
@@ -2519,8 +2589,8 @@
 /** Convert tangent plane coords to (RA,Dec) */
 psCoord *
-psCoordTPtoSky(psCoord *out,            //!< Coordinates to return, or NULL
-               psExposure *exp,         //!< Exposure description
-               psCoord *coord           //!< input TP coordinate
-               );
+psCoordTPtoSky(psCoord *out,		//!< Coordinates to return, or NULL
+	       const psExposure *exp,	//!< Exposure description
+	       const psCoord *coord	//!< input TP coordinate
+	       );
 \end{verbatim}
 
@@ -2528,8 +2598,8 @@
 /** Convert Cell coords to FPA coordinates */
 psCoord *
-psCoordCellToFPA(psCoord *out,          //!< Coordinates to return, or NULL
-                 psCell *cell,          //!< Cell description
-                 psCoord *coord         //!< Input cell coordinates
-                 );
+psCoordCellToFPA(psCoord *out,		//!< Coordinates to return, or NULL
+		 const psCell *cell,	//!< Cell description
+		 const psCoord *coord	//!< Input cell coordinates
+		 );
 \end{verbatim}
 
@@ -2594,18 +2664,17 @@
 fields:
 \begin{verbatim}
-/*
- * 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 *name;                         // Name of item
-    psMetaDataType type;                // type of this item
+    const int id;			//!< unique ID for this item
+    char *restrict name;		//!< Name of item
+    psMetaDataType type;		//!< type of this item
+    psMetaDataFlags flags;		//!< flags associated with this item
     const union {
-        float f;                        // floating value
-        int i;                          // integer value
-        void *v;                        // other type
-    } val;                              // value of metadata
-    char *comment;                      // optional comment ("", not NULL)
+	float f;			//!< floating value
+	int i;				//!< integer value
+	void *v;			//!< other type
+    } val;				//!< value of metadata
+    char *comment;			//!< optional comment ("", not NULL)
+    psDlist *restrict items;		//!< list of psMetaDataItems with the same name
 } psMetaDataItem;
 \end{verbatim}
@@ -2623,17 +2692,16 @@
 \code{psMetaDataType} (see also table \ref{tabMetaDataTypes}); the initial defined values are:
 \begin{verbatim}
-/*
- * Possible types of metadata.  
- */
-typedef enum {                          // type of val is:
-    psMetaFloat,                        // float (.f)
-    psMetaInt,                          // int (.i)
-    psMetaStr,                          // string (.v)
-    psMetaImg,                          // image (.v)
-    psMetaJPEG,                         // JPEG (.v)
-    psMetaPNG,                          // PNG (.v)
-    psMetaAstrom,                       // astrometric coefficients (.v)
-    psMetaUnknown,                      // other (.v)
-    psMetaNType                         // Number of types; must be last
+/** Possible types of metadata. */
+typedef enum {				//!< type of val is:
+    PS_META_ITEM_SET = 0,		//!< NULL; metadata is in psMetaDataType.items
+    PS_META_FLOAT,			//!< float (.f)
+    PS_META_INT,			//!< int (.i)
+    PS_META_STR,			//!< string (.v)
+    PS_META_IMG,			//!< image (.v)
+    PS_META_JPEG,			//!< JPEG (.v)
+    PS_META_PNG,			//!< PNG (.v)
+    PS_META_ASTROM,			//!< astrometric coefficients (.v)
+    PS_META_UNKNOWN,			//!< other (.v)
+    PS_META_NTYPE			//!< Number of types; must be last
 } psMetaDataType;
 \end{verbatim}
@@ -2643,13 +2711,13 @@
 \textbf{Value} & \textbf{Type} & \textbf{member of union} & \textbf{Comments}\\
 \hline
-psMetaFloat & float & f & value, not pointer, is stored \\
-psMetaInt & int & i &  value, not pointer, is stored \\
-psMetaStr & string & v &  value, not pointer to original, is stored \\
-psMetaImg & psImage & v &  \\
-psMetaJPEG & JPEG & v &  \\
-psMetaPNG & PNG & v &  \\
-psMetaAstrom & psAstrom & v &  \\
-psMetaUnknown & other & v &  \\
-psMetaNType & (none) & & The number of types defined
+PS_META_FLOAT & float & f & value, not pointer, is stored \\
+PS_META_INT & int & i &  value, not pointer, is stored \\
+PS_META_STR & string & v &  value, not pointer to original, is stored \\
+PS_META_IMG & psImage & v &  \\
+PS_META_JPEG & JPEG & v &  \\
+PS_META_PNG & PNG & v &  \\
+PS_META_ASTROM & psAstrom & v &  \\
+PS_META_UNKNOWN & other & v &  \\
+PS_META_NTYPE & (none) & & The number of types defined
 \end{tabular}
 \begin{caption}{Supported Metadata Types}
@@ -2662,7 +2730,8 @@
 
 \begin{verbatim}
+/** A set of metadata */
 typedef struct {
-    psDlist *list;                      // list of psMetaDataItem
-    psHash *table;                      // hash table of the same metadata
+    psDlist *restrict list;		//!< list of psMetaDataItem
+    psHash *restrict table;		//!< hash table of the same metadata
 } psMetaDataSet;
 \end{verbatim}
@@ -2745,31 +2814,55 @@
 
 \begin{verbatim}
-psMetaDataItem *psMetaDataItemAlloc(
-    psMetaDataType type,                // type of this piece of metadata
-    const void *val,                    // value of new item
-                                        // N.b. a pointer even if the item
-                                        // is of type e.g. int
-    const char *comment,                // comment associated with item
-    const char *name,                   // name of new item of metadata (may be an sprintf format)
-    ...);                               // possible arguments for name format
-
-void psMetaDataItemFree(psMetaDataItem *ms); // piece of metadata to destroy
-
-psMetaDataSet *psMetaDataSetAlloc(void);          // make a new set of metadata
-void psMetaDataSetDel(psMetaDataSet *ms); // destroy a set of metadata
-
-/*****************************************************************************/
-/*
- * Utilities
- */
-psMetaDataItem *psMetaDataAppend(psMetaDataSet *restrict ms, psMetaDataItem *restrict item);
-psMetaDataItem *psMetaDataRemove(psMetaDataSet *restrict ms, const char *restrict key);
-
-void psMetaDataSetIterator(psMetaDataSet *ms);
-psMetaDataItem *psMetaDataGetNext(psMetaDataSet *ms);
-psMetaDataItem *psMetaDataLookup(const psMetaDataSet *ms, const char *key);
-
-void psMetaDataItemPrint(FILE *fd,              // file descriptor to write to
-                         const psMetaDataItem *ms); // item of metadata to print
+/** Constructor */
+psMetaDataItem *psMetaDataItemAlloc(int typeFlags, //!< type of this piece of metadata + flags
+				    const void *val, //!< value of new item N.b. a pointer even if the item
+					             //!< is of type e.g. int
+				    const char *comment, //!< comment associated with item
+				    const char *name, //!< name of new item of metadata (may be in sprintf
+						      //!< format)
+				    ...	//!< 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 **********************************************************************/
+
+/// Add entry to the end of the metadata set
+psMetaDataItem *psMetaDataAppend(psMetaDataSet *restrict ms, //!< Metadata set to add to
+				 psMetaDataItem *restrict item //!< Metatdata to add
+    );
+
+/// delete entry from the metadata set
+psMetaDataItem *psMetaDataRemove(psMetaDataSet *restrict ms, //!< Metadata set to delete from
+				 const char *restrict key //!< Key to delete
+    );
+
+/// reset the iterator to the start of the list
+void psMetaDataSetIterator(psMetaDataSet *ms //!< Metadata set to set iterator for
+    );
+
+/// get the next entry in the sequence
+psMetaDataItem *psMetaDataGetNext(psMetaDataSet *restrict ms, //!< Metadata set to get from
+				  const char *restrict match //!< Match this
+    );
+
+/// find the metadata with the specified key
+psMetaDataItem *psMetaDataLookup(const psMetaDataSet *restrict ms, //!< Metadata set to look up
+				 const char *restrict key //!< Key to find
+    );
+
+/// print metadata item to the specified stream
+void psMetaDataItemPrint(FILE *fd,		//!< file descriptor to write to
+			 const psMetaDataItem *restrict ms, //!< item of metadata to print
+			 const char *prefix	   //!< print this at the beginning of each line
+    );
 \end{verbatim}
 
@@ -2834,16 +2927,18 @@
 \begin{verbatim}
 /** apply the coordinate transformation to the given coordinate */
-psCoord *psCoordXformApply (psCoordXform *frame, ///< coordinate transformation
-                            psCoord *coords) ///< input coordiate
-;
+psCoord *psCoordXformApply (psCoord *out, //!< Output coordinates, or NULL
+			    const psCoordXform *frame, ///< coordinate transformation
+			    const psCoord *coords ///< input coordiate
+    );
 \end{verbatim}
 
 \begin{verbatim}
 /** apply the optical distortion to the given coordinate, magnitude, color */
-psCoord *psDistortionApply (psDistortion *pattern, ///< optical distortion pattern
-psCoord *coords,                        ///< input coordinate
-float mag,                              ///< magnitude of object
-float color)                            ///< color of object
-;
+psCoord *psDistortionApply (psCoord *out, //!< Output coordinates, or NULL
+			    const psdistortion *pattern, ///< optical distortion pattern
+			    const psCoord *coords, ///< input coordinate
+			    float mag,	///< magnitude of object
+			    float color ///< color of object
+    );
 \end{verbatim}
 
@@ -2858,6 +2953,6 @@
 psCoord *
 psGetOffset(const psCoord *restrict position1, //!< Position 1
-            const psCoord *restrict position2, //!< Position 2
-            const char *type            //!< Type of offset: Linear, Spherical/Arcsec, Spherical/Degreees etc
+	    const psCoord *restrict position2, //!< Position 2
+	    const char *type		//!< Type of offset: Linear, Spherical/Arcsec, Spherical/Degreees etc
     );
 \end{verbatim}
@@ -2867,6 +2962,6 @@
 psCoord *
 psApplyOffset(const psCoord *restrict position, //!< Position
-              const psCoord *restrict offset, //!< Offset
-              const char *type          //!< Type of offset: Linear, Spherical/Arcsec, Spherical/Degreees etc
+	      const psCoord *restrict offset, //!< Offset
+	      const char *type		//!< Type of offset: Linear, Spherical/Arcsec, Spherical/Degreees etc
     );
 \end{verbatim}
@@ -2881,6 +2976,6 @@
 /** Get Sun Position */
 psCoord *
-psGetSunPos(float mjd)                  //!< MJD to get position for
-;
+psGetSunPos(float mjd			//!< MJD to get position for
+    );
 \end{verbatim}
 
@@ -2888,8 +2983,8 @@
 /** Get Moon position */
 psCoord *
-psGetMoonPos(float mjd,                 //!< MJD to get position for
-             double latitude,           //!< Latitude for apparent position
-             double longitude)          //!< Longitude for apparent position
-;
+psGetMoonPos(float mjd,			//!< MJD to get position for
+	     double latitude,		//!< Latitude for apparent position
+	     double longitude		//!< Longitude for apparent position
+    );
 \end{verbatim}
 
@@ -2897,6 +2992,6 @@
 /** Get Moon phase */
 float
-psGetMoonPhase(float mjd)               //!< MJD to get phase for
-;
+psGetMoonPhase(float mjd		//!< MJD to get phase for
+    );
 \end{verbatim}
 
@@ -2904,7 +2999,7 @@
 /** Get Planet positions */
 psCoord *
-psGetSolarSystemPos(char *solarSystemObject, //!< Named S.S. object
-                    float mjd)          //!< MJD to get position for
-;
+psGetSolarSystemPos(const char *solarSystemObject, //!< Named S.S. object
+		    float mjd		//!< MJD to get position for
+    );
 \end{verbatim}
 
@@ -2917,6 +3012,6 @@
 /** Convert ICRS to Ecliptic */
 psCoord *
-psCoordinatesItoE(const psCoord *restrict coordinates) //!< ICRS coordinates to convert
-;
+psCoordinatesItoE(const psCoord *restrict coordinates //!< ICRS coordinates to convert
+    );
 \end{verbatim}
 
@@ -2924,6 +3019,6 @@
 /** Convert Ecliptic to ICRS */
 psCoord *
-psCoordinatesEtoI(const psCoord *restrict coordinates) //!< Ecliptic coordinates to convert
-;
+psCoordinatesEtoI(const psCoord *restrict coordinates //!< Ecliptic coordinates to convert
+    );
 \end{verbatim}
 
@@ -2931,6 +3026,6 @@
 /** Convert ICRS to Galactic */
 psCoord *
-psCoordinatesItoG(const psCoord *restrict coordinates) //!< ICRS coordinates to convert
-;
+psCoordinatesItoG(const psCoord *restrict coordinates //!< ICRS coordinates to convert
+    );
 \end{verbatim}
 
@@ -2938,6 +3033,6 @@
 /** Convert Galactic to ICRS */
 psCoord *
-psCoordinatesGtoI(const psCoord *restrict coordinates) //!< Galactic coordinates to convert
-;
+psCoordinatesGtoI(const psCoord *restrict coordinates //!< Galactic coordinates to convert
+    );
 \end{verbatim}