Commit cc1e1546 authored by Karl Wette's avatar Karl Wette

Doxygen: reformat comments as box comments, clean up whitespace

Original: 668b805686eb8deeb6027222db27867d743d7d2a
parent 9e20ec31
......@@ -18,31 +18,31 @@
*/
/**
\file
\author Jolien Creighton
\brief Prints the version and configure options of the LAL library being used.
\heading{Usage}
\code
lal-version
\endcode
\heading{Description}
This program prints the current version of LAL.\@ If the version information
in the library differs from the version information in the header file, this
program prints the two versions and exits with code 1. This is useful for
determining which version of the LAL library and header files you are linking
to.
\heading{Exit codes}
<table><tr><th> Code</th><th>Explanation</th></tr>
<tr><td> 0</td><td>Success, normal exit.</td></tr>
<tr><td> 1</td><td>Version info in library disagrees with header file.</td></tr>
<tr><td> 2</td><td>Subroutine failed.</td></tr>
</table>
*/
* \file
* \author Jolien Creighton
* \brief Prints the version and configure options of the LAL library being used.
*
* \heading{Usage}
* \code
* lal-version
* \endcode
*
* \heading{Description}
*
* This program prints the current version of LAL.\@ If the version information
* in the library differs from the version information in the header file, this
* program prints the two versions and exits with code 1. This is useful for
* determining which version of the LAL library and header files you are linking
* to.
*
* \heading{Exit codes}
* <table><tr><th> Code</th><th>Explanation</th></tr>
* <tr><td> 0</td><td>Success, normal exit.</td></tr>
* <tr><td> 1</td><td>Version info in library disagrees with header file.</td></tr>
* <tr><td> 2</td><td>Subroutine failed.</td></tr>
* </table>
*
*/
#include <stdio.h>
#include <string.h>
......
/**
\addtogroup pkg_support
\brief This package covers LAL support routines.
These routines do not conform to LAL requirements, and many of them should be
used only for debugging and in test code, not in production code. These are
compiled and installed as a separate library \c lalsupport.
@{
\defgroup FileIO_h Header FileIO.h
\defgroup PrintVector_h Header PrintVector.h
\defgroup PrintFTSeries_h Header PrintFTSeries.h
\defgroup ReadFTSeries_h Header ReadFTSeries.h
\defgroup ReadNoiseSpectrum_h Header ReadNoiseSpectrum.h
\defgroup StreamInput_h Header StreamInput.h
\defgroup StreamOutput_h Header StreamOutput.h
\defgroup ConfigFile_h Header ConfigFile.h
\defgroup UserInput_h Header UserInput.h
\defgroup LALMathematica_h Header LALMathematica.h
\defgroup LogPrintf_h Header LogPrintf.h
\defgroup SegmentsIO_h Header SegmentsIO.h
@}
*/
* \addtogroup pkg_support
*
* \brief This package covers LAL support routines.
*
* These routines do not conform to LAL requirements, and many of them should be
* used only for debugging and in test code, not in production code. These are
* compiled and installed as a separate library \c lalsupport.
*
* @{
* \defgroup FileIO_h Header FileIO.h
* \defgroup PrintVector_h Header PrintVector.h
* \defgroup PrintFTSeries_h Header PrintFTSeries.h
* \defgroup ReadFTSeries_h Header ReadFTSeries.h
* \defgroup ReadNoiseSpectrum_h Header ReadNoiseSpectrum.h
* \defgroup StreamInput_h Header StreamInput.h
* \defgroup StreamOutput_h Header StreamOutput.h
* \defgroup ConfigFile_h Header ConfigFile.h
* \defgroup UserInput_h Header UserInput.h
* \defgroup LALMathematica_h Header LALMathematica.h
* \defgroup LogPrintf_h Header LogPrintf.h
* \defgroup SegmentsIO_h Header SegmentsIO.h
*
* @}
*
*/
......@@ -18,7 +18,8 @@
*/
/* vim: set noet ts=4 sw=4: */
/** \file
/**
* \file
* \ingroup std
* \author Creighton, J. D. E.
* \brief Routines for exporting time series data as sound files.
......
......@@ -28,85 +28,82 @@
extern "C" {
#endif
/** \addtogroup ConfigFile_h
/**
* \addtogroup ConfigFile_h
* \author Reinhard Prix
* \brief Module for general parsing of simple ASCII-based config-files.
\heading{Description}
This module provides routines for reading formatted
config-files containing definitions of the form <tt>variable = value</tt>.
The general syntax is somewhat similar to the one provided by the
perl-module <tt>ConfigParser</tt> (cf.
http://www.python.org/doc/current/lib/module-ConfigParser.html)
Comments are allowed using either '<tt>\#</tt>' or <tt>\%</tt>.
You can also use line-continuation using a '<tt>\\</tt>' at the end of the line.
Also note that comment-signs '<tt>\#\%</tt>' within double-quotes &quot;...&quot;
are <em>not</em> treated as comment-characters.
Semi-colons <tt>;</tt> are ignored, but can be used to separate several assignments on the same line.
The general syntax is best illustrated
using a simple example:
\code
# comment line
var1 = 1.0; var2 = 3.1; ## several assignments on a line, separated by ';'
somevar = some text.\
You can also use\
line-continuation
var3 = 4 # whatever that means
note = "this is also possible, and # here does nothing"
a_switch = true #possible values: 0,1,true,false,yes,no, case insensitive
...
\endcode
Note that TABS generally get replaced by a single space, which can be
useful in the case of line-continuation (see example). All leading and
trailing spaces in are ignore (except within double-quotes).
The general approach of reading from such a config-file, is to first
call XLALParseDataFile() which loads and pre-parses the contents of the
config-file into the structure LALParsedDataFile. Then one can read in
config-variables either using one of the type-strict custom-wrappers
<tt>XLALReadConfig<TYPE>Variable()</tt> or the general-purpose reading function
XLALReadConfigVariable().
A boolean variable read by XLALReadConfigBOOLVariable() can have any of the values
<tt>{1, 0, yes, no, true, false}</tt>, where the comparison is done
<em>case-insensitively</em>, i.e. you can also use 'True' or 'FALSE'....
If one wishes a tight sytnax for the config-file, one can check
that there are no illegal entries in the config-file. This is done
by checking at the end that all config-file entries have been
successfully parsed, using:
XLALCheckConfigReadComplete(), where \a strictness is either
CONFIGFILE_WARN or CONFIGFILE_ERROR.
In the first case only a warning is issued, while in the second it is
treated as a LAL-error if some config-file entries have not been
read-in. (The use of this function is optional).
The configfile-data should be freed at the end using
XLALDestroyParsedDataFile().
\par Notes
XLALReadConfigSTRINGVariable() and XLALReadConfigSTRINGVariable() are not
the same as using <tt>%quot;\%s&quot;</tt> as a format string, as they read the
<em>rest</em> of the logical line (excluding comments) as a string.
In the case of XLALReadConfigSTRINGVariable(), the required
memory is allocated and has to be freed by the caller, while for
XLALReadConfigSTRINGVariable() the caller has to provide a
CHARVector of length N, which defines the maximum length of
string to be read.
\note instead of using these functions directly, it might be
more convenient to use the \ref UserInput_h.
*/
*
* \heading{Description}
*
* This module provides routines for reading formatted
* config-files containing definitions of the form <tt>variable = value</tt>.
* The general syntax is somewhat similar to the one provided by the
* perl-module <tt>ConfigParser</tt> (cf.
* http://www.python.org/doc/current/lib/module-ConfigParser.html)
*
* Comments are allowed using either '<tt>\#</tt>' or <tt>\%</tt>.
* You can also use line-continuation using a '<tt>\\</tt>' at the end of the line.
* Also note that comment-signs '<tt>\#\%</tt>' within double-quotes &quot;...&quot;
* are <em>not</em> treated as comment-characters.
* Semi-colons <tt>;</tt> are ignored, but can be used to separate several assignments on the same line.
* The general syntax is best illustrated
* using a simple example:
* \code
* # comment line
* var1 = 1.0; var2 = 3.1; ## several assignments on a line, separated by ';'
* somevar = some text.\
* You can also use\
* line-continuation
* var3 = 4 # whatever that means
* note = "this is also possible, and # here does nothing"
* a_switch = true #possible values: 0,1,true,false,yes,no, case insensitive
* ...
* \endcode
*
* Note that TABS generally get replaced by a single space, which can be
* useful in the case of line-continuation (see example). All leading and
* trailing spaces in are ignore (except within double-quotes).
*
* The general approach of reading from such a config-file, is to first
* call XLALParseDataFile() which loads and pre-parses the contents of the
* config-file into the structure LALParsedDataFile. Then one can read in
* config-variables either using one of the type-strict custom-wrappers
* <tt>XLALReadConfig<TYPE>Variable()</tt> or the general-purpose reading function
* XLALReadConfigVariable().
*
* A boolean variable read by XLALReadConfigBOOLVariable() can have any of the values
* <tt>{1, 0, yes, no, true, false}</tt>, where the comparison is done
* <em>case-insensitively</em>, i.e. you can also use 'True' or 'FALSE'....
*
* If one wishes a tight sytnax for the config-file, one can check
* that there are no illegal entries in the config-file. This is done
* by checking at the end that all config-file entries have been
* successfully parsed, using:
* XLALCheckConfigReadComplete(), where \a strictness is either
* CONFIGFILE_WARN or CONFIGFILE_ERROR.
* In the first case only a warning is issued, while in the second it is
* treated as a LAL-error if some config-file entries have not been
* read-in. (The use of this function is optional).
*
* The configfile-data should be freed at the end using
* XLALDestroyParsedDataFile().
*