remove stale routine, add some documentation

git-svn-id: svn+ssh://svn.gnucash.org/repo/gnucash/trunk@8502 57a11ea4-9604-0410-9ed3-97b8803252fd

src/engine/date.c

@@ -932,15 +932,6 @@ xaccDMYToSec (int day, int month, int year)
   return secs;
 }
 
-time_t
-xaccScanDateS (const char *str)
-{
-  int month, day, year;
-
-  scanDate (str, &day, &month, &year);
-
-  return xaccDMYToSec (day,month,year);
-}
 
 #define THIRTY_TWO_YEARS 0x3c30fc00LL
 

src/engine/date.h

@@ -201,6 +201,7 @@ time_t xaccDMYToSec (int day, int month, int year);
 long int gnc_timezone (struct tm *tm);
 
 
+/* ------------------------------------------------------------------------ */
 /** @name DateFormat functions */
 /*@{*/
 /** DOCUMENT ME! */
@@ -213,6 +214,17 @@ const gchar *getDateFormatString(DateFormat df);
 const gchar *getDateTextFormatString(DateFormat df);
 /*@}*/
 
+/** dateSeparator
+ *    Return the field separator for the current date format
+ *
+ * Args:   none
+ *
+ * Return: date character
+ *
+ * Globals: global dateFormat value
+ */
+char dateSeparator(void);
+
 /** @name Date Printing/Scanning functions 
  *
  * \warning HACK ALERT -- the scan and print routines should probably
@@ -244,10 +256,17 @@ void printDateSecs (char * buff, time_t secs);
 /** Convenience; calls through to printDate(). **/
 void printGDate( char *buf, GDate *gd );
 
-/** DOCUMENT ME! */
+/** Convenience; calls through to printDate(). 
+ *  Return: string, which should be freed when no longer needed.
+ * **/
 char * xaccPrintDateSecs (time_t secs);
 
-/** DOCUMENT ME! */
+/** Convenience; calls through to printDate(). 
+ *  Return: static global string.
+ *  \warning This routine is not thread-safe, because it uses a single
+ *      global buffer to store the return value.  Use printDateSecs()
+ *      or xaccPrintDateSecs instead.
+ * **/
 const char * gnc_print_date(Timespec ts);
 
 /** The xaccDateUtilGetStamp() routine will take the given time in
@@ -257,17 +276,6 @@ const char * gnc_print_date(Timespec ts);
  *  @note The caller owns this buffer and must free it when done. */
 char *xaccDateUtilGetStamp (time_t thyme);
 
-/** dateSeparator
- *    Return the field separator for the current date format
- *
- * Args:   none
- *
- * Return: date character
- *
- * Globals: global dateFormat value
- */
-char dateSeparator(void);
-
 /** scanDate
  *    Convert a string into  day / month / year integers according to
  *    the current dateFormat value.
@@ -283,12 +291,6 @@ char dateSeparator(void);
  */
 void scanDate (const char *buff, int *day, int *month, int *year);
 
-/** \warning hack alert XXX FIXME -- these date routines return incorrect
- * values for dates before 1970.  Most of them are good only up 
- * till 2038.  This needs fixing ... */
-time_t xaccScanDateS (const char *buff);
-/*@}*/
-
 
 /** @name Date Start/End Adjustment routines
  * Given a time value, adjust it to be the beginning or end of that day.