Index: unk/pvosummary
===================================================================
--- /trunk/pvosummary	(revision 58)
+++ 	(revision )
@@ -1,26 +1,0 @@
-#!/bin/bash
-
-#foreach fname (`ls *.fits`)
-#    echo pvovap $fname
-#    pvovap $fname
-#end
-DIR=/u/whi550/bin
-
-if [ $# == 0 ]; then
-    for fname in `ls *.fits 2> /dev/null`; do
-	${DIR}/pvosummary.x $fname 2> /dev/null
-    done
-    for fname in `ls *.rf 2> /dev/null`; do
-	${DIR}/pvosummary.x $fname 2> /dev/null
-    done
-elif [ $1 == "-h" ]; then
-    echo Usage: 
-    echo 1. pvosummary [FILE] 
-    echo 2. pvosummary
-    echo ---------
-    echo 1. Prints RA, DEC, DATE-OBS for single FITS file.
-    echo 2. Prints RA, DEC, DATE-OBS for all fits files in the current directory.
-    echo Note that if a keyword is not present, --- is printed.
-else
-    ${DIR}/pvosummary.x $1 2> /dev/null
-fi
Index: /trunk/src/pvo-FITS-fileIO.cc
===================================================================
--- /trunk/src/pvo-FITS-fileIO.cc	(revision 58)
+++ /trunk/src/pvo-FITS-fileIO.cc	(revision 59)
@@ -523,6 +523,7 @@
        *
        *   NOTHING LEFT TO DO HERE.
-       */
-    
+       *  \deprecated
+       */
+      return;
     }
     //-----------------------------------------------------------------------
@@ -534,6 +535,4 @@
        * extension. This is just a row of today's date and what was entered
        * in the command line.
-       * \param argc The number of command line arguments.
-       * \param argv Each command line argument.
        */
     
@@ -567,6 +566,4 @@
        * extension. This is just a row of today's date and what was entered
        * in the command line.
-       * \param argc The number of command line arguments.
-       * \param argv Each command line argument.
        */
     
Index: /trunk/src/pvo-FITS.cc
===================================================================
--- /trunk/src/pvo-FITS.cc	(revision 58)
+++ /trunk/src/pvo-FITS.cc	(revision 59)
@@ -300,5 +300,6 @@
     {
       /**
-       *   Finds the keyword "name" in the current header unit, returning the value in the "value" parameter.
+       *   Finds the keyword "name" in the current header unit,
+       *   returning the value in the "value" parameter.
        *   A templated function that should work for all cases.
        *  \param name The name of the keyword.
@@ -335,5 +336,5 @@
     
   
-    //------------------------------------------------------------------------
+    //------------------------------------------------------------------------  
 
     int PSRFits::getColnum(char *name)
Index: /trunk/src/pvo-utils.cc
===================================================================
--- /trunk/src/pvo-utils.cc	(revision 58)
+++ /trunk/src/pvo-utils.cc	(revision 59)
@@ -351,4 +351,14 @@
 		std::string ra2, std::string dec2)
   {
+    /**
+     *  Calculates the angular separation between two sky positions,
+     *  given as strings for RA and DEC. Uses the function
+     *  angSep(double,double,double,double).
+     * \param ra1 The right ascension for the first position.
+     * \param dec1 The declination for the first position.
+     * \param ra2 The right ascension for the second position.
+     * \param dec2 The declination for the second position.
+     * \return The angular separation in degrees.
+     */
     if((ra1==ra2)&&(dec1==dec2)) 
       return 0.;
@@ -360,4 +370,13 @@
   double angSep(double ra1, double dec1, double ra2, double dec2)
   {
+    /**
+     *  Calculates the angular separation between two sky positions,
+     *  where RA and DEC are given in decimal degrees.
+     * \param ra1 The right ascension for the first position.
+     * \param dec1 The declination for the first position.
+     * \param ra2 The right ascension for the second position.
+     * \param dec2 The declination for the second position.
+     * \return The angular separation in degrees.
+     */
     double r1,d1,r2,d2;
     r1 = ra1  * M_PI / 180.;
Index: /trunk/src/pvo-utils.hh
===================================================================
--- /trunk/src/pvo-utils.hh	(revision 58)
+++ /trunk/src/pvo-utils.hh	(revision 59)
@@ -8,17 +8,50 @@
 {
 
-//   static bool verbose;
-  
-  /** Report a general error, along with the offending function. */
-  void PVOError(std::string subroutine, std::string error);
-  
-  const std::string pvoconvert_help_msg = 
+  /** Help text for pvoconvert -h */
+  const std::string pvoconvert_usage_text = 
 "Usage: pvoconvert [options] <fits file>\n\
   Options:\n\
   -H  Use the PH (High Latitude) Survey settings, rather than the PM/Multibeam Survey\n\
   -h  Display this help page.\n\
-  -v  Verbose mode for error/warning messages.\n";
+  -v  Verbose mode for error/warning messages.\n\
+---------\n\n\
+ PVOConvert converts pulsar survey data into PSRFITS format.\n\
+ It can distinguish between the 70cm data and 21cm Multibeam data, but to specify\n\
+  particular data as coming from the High Latitude survey rather than the standard\n\
+  Multibeam survey, use the -h option.\n\
+ Output files will be encoded according to the survey and date & time of observation.\n";
 
+  /** Help text for pvosummary -h */
+  const std::string pvosummary_usage_text = 
+"Usage:\n\
+  1. pvosummary [FILE]\n\
+  2. pvosummary\n\
+  3. pvosummary -h\n\
+---------\n\
+  1. Prints RA, DEC, BEAM FWHM, DATE-OBS for single FITS file.\n\
+  2. Prints RA, DEC, BEAM FWHM, DATE-OBS for all FITS files in the current directory.\n\
+  3. Prints this help information.\n\
+ Note that if a keyword is not present, --- is printed.\n\
+ FITS files are assumed to have suffixes of .fits or .rf\n";
 
+  /** Help text for pvoconesearch -h */
+  const std::string pvoconesearch_usage_text = 
+"Usage:\n\
+  1. pvoconesearch ra dec radius\n\
+  2. pvoconesearch -h\n\
+---------\n\
+  1. Prints RA, DEC, BEAM FWHM, DATE-OBS, OFFSET for all FITS files that\n\
+     lie within \"radius\" of the position given by ra, dec.\n\
+     OFFSET is angular offset from query position.\n\
+  2. Prints this help information.\n\n\
+ The RA and DEC can be in the form hh:mm:ss.ss etc or in decimal degrees.\n\
+ The search radius is in degrees. The beam size is also taken into account,\n\
+  so the effective search radius becomes (radius + 0.5*beamFWHM).\n\
+ Note that if a keyword is not present, --- is printed.\n\
+ FITS files are assumed to have suffixes of .fits or .rf\n";
+
+  /** Report a general error, along with the offending function. */
+  void PVOError(std::string subroutine, std::string error);
+  
   /** Return the filename of the defintion file of the PSRFITS format. */
   inline std::string getPSRFITSdefn(){ 
Index: /trunk/src/pvoconesearch.cc
===================================================================
--- /trunk/src/pvoconesearch.cc	(revision 58)
+++ /trunk/src/pvoconesearch.cc	(revision 59)
@@ -17,21 +17,32 @@
 
 
-const std::string help_text = 
-"Usage:\n\
-  1. pvoconesearch ra dec radius\n\
-  2. pvoconesearch -h\n\
----------\n\
-  1. Prints RA, DEC, BEAM FWHM, DATE-OBS, OFFSET for all FITS files that\n\
-     lie within \"radius\" of the position given by ra, dec.\n\
-     OFFSET is angular offset from query position.\n\
-  2. Prints this help information.\n\n\
- The RA and DEC can be in the form hh:mm:ss.ss etc or in decimal degrees.\n\
- The search radius is in degrees. The beam size is also taken into account,\n\
-  so the effective search radius becomes (radius + 0.5*beamFWHM).\n\
- Note that if a keyword is not present, --- is printed.\n\
- FITS files are assumed to have suffixes of .fits or .rf\n";
-
 int main(int argc, char * argv[])
 {
+  /** 
+   * PVOConeSearch is a function to do basic cone searching in PSRFITS files.
+   *
+   * This program is a command-line program that looks at all PSRFITS
+   * files in the current directory (i.e. files that have extensions
+   * .fits or .rf) and returns all those that cover sky within a given
+   * search radius of a given RA,DEC position. 
+   *
+   * The format of usage is: <br> 
+   * <tt>> pvoconesearch RA DEC RADIUS</tt><br> 
+   * RA and DEC can be in either decimal degrees or hms/dms
+   * format (i.e.  hh:mm:ss.sss for RA and dd:mm:ss.sss for
+   * DEC). Entering <br>
+   * <tt>> pvoconesearch -h</tt><br>
+   * will give a help message, using PVO::pvoconesearch_usage_text.
+   *
+   * The output is a list of valid files, their central RA & DEC,
+   * their beam size, the DATE-OBS keyword (time/date of observation),
+   * plus the angular offset [deg] from the query position. The beam
+   * size of the FITS file is taken into account, so that the central
+   * position can be more than RADIUS away from the query position (as
+   * long as the query position is still within the primary beam's
+   * FWHM).
+   * 
+   */
+
 
   bool verboseflag = false;
@@ -76,7 +87,7 @@
   default:
     if(argc==2 && strcmp(argv[1],"-h")==0)
-      std::cout << help_text;
+      std::cout << pvoconesearch_usage_text;
     else
-      std::cerr << help_text;
+      std::cerr << pvoconesearch_usage_text;
     return 0;
     break;
Index: /trunk/src/pvoconvert.cc
===================================================================
--- /trunk/src/pvoconvert.cc	(revision 58)
+++ /trunk/src/pvoconvert.cc	(revision 59)
@@ -18,4 +18,33 @@
 int main(int argc, char * argv[])
 {
+  /** 
+   * PVOConvert is a function that converts pulsar survey data into a
+   * standard PSRFITS format.
+   *
+   * This program is a command-line program that accepts an existing
+   * file as an argument. It works out what survey the data is from
+   * (based initially on the first few bytes of the file, and also
+   * using the input flags -- see below), and uses this information to
+   * interpret the header blocks.
+   *
+   * The binary data is written to the SUBINT binary table extension,
+   * and a record of the command-line statement is written to the
+   * HISTORY table. No other tables are written.
+   *
+   * The format of usage is: <br> 
+   * <tt>> pvoconvert FILE </tt><br>
+   * If the input FILE is from the Parkes High Latitude Multibeam
+   * Survey (PH, Burgay et al. 2006), one needs to use the <tt>-H</tt>
+   * flag to use the PH settings (for integration time etc), rather
+   * than those of the Multibeam survey (PM, Manchester et
+   * al. 2001):<br>
+   * <tt>> pvoconvert -H FILE </tt><br>
+   * Using the <tt>-v</tt> option means all error messages will be
+   * displayed. Entering<br>
+   * <tt>> pvosummary -h</tt><br>
+   * will give a help message, using PVO::pvoconvert_usage_text.
+   *
+   */
+
   PSRFits fitsfile;
   fitsfile.setVerbosity(false);
Index: /trunk/src/pvosummary.cc
===================================================================
--- /trunk/src/pvosummary.cc	(revision 58)
+++ /trunk/src/pvosummary.cc	(revision 59)
@@ -17,18 +17,28 @@
 
 
-const std::string help_text = 
-"Usage:\n\
-  1. pvosummary [FILE]\n\
-  2. pvosummary\n\
-  3. pvosummary -h\n\
----------\n\
-  1. Prints RA, DEC, BEAM FWHM, DATE-OBS for single FITS file.\n\
-  2. Prints RA, DEC, BEAM FWHM, DATE-OBS for all FITS files in the current directory.\n\
-  3. Prints this help information.\n\
- Note that if a keyword is not present, --- is printed.\n\
- FITS files are assumed to have suffixes of .fits or .rf\n";
-
 int main(int argc, char * argv[])
 {
+  /** 
+   * PVOSummary is a function to print out basic information for
+   * PSRFITS files.
+   *
+   * This program is a command-line program that looks at PSRFITS
+   * files (i.e. files that have extensions .fits or .rf) and returns
+   * a summary of their positions, beam sizes and observation times.
+   *
+   * The format of usage is: <br> 
+   * <tt>> pvosummary </tt><br>
+   * to analyse all PSRFITS files in the current directory, or <br>
+   * <tt>> pvosummary FILE</tt><br>
+   * to analyse the file FILE. Entering<br>
+   * <tt>> pvosummary -h</tt><br>
+   * will give a help message, using PVO::pvosummary_usage_text.
+   *
+   * The output is a list of valid files, their central RA & DEC,
+   * their beam size, and the DATE-OBS keyword (time/date of
+   * observation),
+   * 
+   */
+
 
   bool verboseflag = false;
@@ -51,5 +61,5 @@
   case 2:
     if(strcmp(argv[1],"-h")==0){
-      std::cout << help_text;
+      std::cout << pvosummary_usage_text;
       return 0;
     }
@@ -58,5 +68,5 @@
     break;
   default:
-    std::cerr << help_text;
+    std::cerr << pvosummary_usage_text;
     return 0;
     break;
