aboutsummaryrefslogtreecommitdiff
path: root/libcrystfel/src/stream.c
diff options
context:
space:
mode:
authorThomas White <taw@physics.org>2019-05-07 16:10:17 +0200
committerThomas White <taw@physics.org>2019-05-07 16:25:44 +0200
commit1bed7848a99aba510726b3fa287b1d7a3f75dfa6 (patch)
treeddeea6dc2a6a23c80a8d5f76ae8fd4548b8ac3c7 /libcrystfel/src/stream.c
parent66ec127e34d2f732e65be61897347edf17bdb4e1 (diff)
Update all source code comments to Doxygen format
Diffstat (limited to 'libcrystfel/src/stream.c')
-rw-r--r--libcrystfel/src/stream.c124
1 files changed, 73 insertions, 51 deletions
diff --git a/libcrystfel/src/stream.c b/libcrystfel/src/stream.c
index 66b3b657..5aac2eab 100644
--- a/libcrystfel/src/stream.c
+++ b/libcrystfel/src/stream.c
@@ -52,6 +52,8 @@
#include "reflist.h"
#include "reflist-utils.h"
+/** \file stream.h */
+
#define LATEST_MAJOR_VERSION (2)
#define LATEST_MINOR_VERSION (3)
@@ -816,6 +818,18 @@ static int write_crystal(Stream *st, Crystal *cr, int include_reflections)
}
+/**
+ * \param st A \ref Stream
+ * \param i An \ref image structure
+ * \param imfile A \ref imagefile structure
+ * \param include_peaks Whether to include peak search results in stream
+ * \param include_reflections Whether to include integration results in stream
+ * \param ev A \ref event strucutre
+ *
+ * Writes a new chunk to \p st.
+ *
+ * \returns non-zero on error.
+ */
int write_chunk(Stream *st, struct image *i, struct imagefile *imfile,
int include_peaks, int include_reflections, struct event *ev)
{
@@ -1180,7 +1194,9 @@ static int read_and_store_field(struct image *image, const char *line)
}
-/* Read the next chunk from a stream and fill in 'image' */
+/**
+ * Read the next chunk from a stream and fill in 'image'
+ */
int read_chunk_2(Stream *st, struct image *image, StreamReadFlags srf)
{
char line[1024];
@@ -1332,6 +1348,15 @@ int read_chunk_2(Stream *st, struct image *image, StreamReadFlags srf)
}
+
+/**
+ * \param st A \ref Stream
+ * \param image An \ref image structure to be filled
+ *
+ * Reads a chunk from \p st, placing the information in \p image.
+ *
+ * \returns non-zero on error.
+ */
int read_chunk(Stream *st, struct image *image)
{
return read_chunk_2(st, image, STREAM_READ_UNITCELL
@@ -1469,18 +1494,17 @@ Stream *open_stream_for_read(const char *filename)
/**
- * open_stream_fd_for_write
- * @fd: File descriptor (e.g. from open()) to use for stream data.
+ * \param fd File descriptor (e.g. from open()) to use for stream data.
*
- * Creates a new %Stream from @fd, so that stream data can be written to @fd
- * using write_chunk().
+ * Creates a new \ref Stream from \p fd, so that stream data can be written to \p fd
+ * using \ref write_chunk.
*
- * In contrast to open_stream_for_write(), this function does not write any of
+ * In contrast to \ref open_stream_for_write, this function does not write any of
* the usual headers. This function is mostly for use when multiple substreams
* need to be multiplexed into a single master stream. The master would be
- * opened using open_stream_for_write(), and the substreams using this function.
+ * opened using \ref open_stream_for_write, and the substreams using this function.
*
- * Returns: a %Stream, or NULL on failure.
+ * \returns A \ref Stream, or NULL on failure.
*/
Stream *open_stream_fd_for_write(int fd)
{
@@ -1517,19 +1541,18 @@ static void write_cell_to_stream(Stream *st, UnitCell *cell)
/**
- * open_stream_for_write_4
- * @filename: Filename of new stream
- * @geom_filename: The geometry filename to copy
- * @cell: A %UnitCell to write into the stream
- * @argc: The number of arguments to the program
- * @argv: The arguments to the program
- * @indm_str: The list of indexing methods
+ * \param filename Filename of new stream
+ * \param geom_filename The geometry filename to copy
+ * \param cell A \ref UnitCell to write into the stream
+ * \param argc The number of arguments to the program
+ * \param argv The arguments to the program
+ * \param indm_str The list of indexing methods
*
- * Creates a new stream with name @filename, and adds the stream format
+ * Creates a new stream with name \p filename, and adds the stream format
* and version header, plus a verbatim copy of the geometry file and the unit
* cell in CrystFEL format.
*
- * Returns: a %Stream, or NULL on failure.
+ * \returns A \ref Stream, or NULL on failure.
*/
Stream *open_stream_for_write_4(const char *filename,
const char *geom_filename, UnitCell *cell,
@@ -1586,16 +1609,15 @@ Stream *open_stream_for_write_3(const char *filename,
/**
- * open_stream_for_write_2
- * @filename: Filename of new stream
- * @geom_filename: The geometry filename to copy
- * @argc: The number of arguments to the program
- * @argv: The arguments to the program
+ * \param filename Filename of new stream
+ * \param geom_filename The geometry filename to copy
+ * \param argc The number of arguments to the program
+ * \param argv The arguments to the program
*
- * Creates a new stream with name @filename, and adds the stream format
+ * Creates a new stream with name \p filename, and adds the stream format
* and version header, plus a verbatim copy of the geometry file
*
- * Returns: a %Stream, or NULL on failure.
+ * \returns A \ref Stream, or NULL on failure.
*/
Stream *open_stream_for_write_2(const char *filename,
const char *geom_filename, int argc,
@@ -1636,16 +1658,15 @@ Stream *open_stream_for_write_2(const char *filename,
/**
- * open_stream_for_write
- * @filename: Filename of new stream
+ * \param filename Filename of new stream
*
- * Creates a new stream with name @filename, and adds the stream format
+ * Creates a new stream with name \p filename, and adds the stream format
* and version headers.
*
- * You may want to follow this with a call to write_command() to record the
+ * You may want to follow this with a call to \ref write_command to record the
* command line.
*
- * Returns: a %Stream, or NULL on failure.
+ * \returns A \ref Stream, or NULL on failure.
*/
Stream *open_stream_for_write(const char *filename)
{
@@ -1654,17 +1675,16 @@ Stream *open_stream_for_write(const char *filename)
/**
- * get_stream_fd
- * @st: A %Stream
+ * \param st A \ref Stream
*
- * This function gets the integer file descriptor for @st, a bit like fileno().
+ * This function gets the integer file descriptor for \p st, a bit like fileno().
*
- * This is useful in conjunction with open_stream_fd_for_write(), to get the
+ * This is useful in conjunction with \ref open_stream_fd_for_write, to get the
* underlying file descriptor to which the multiplexed stream data should be
* written. In this case, the only other operations you should ever do (or have
- * done) on @st are open_stream_for_write() and close_stream().
+ * done) on \p st are \ref open_stream_for_write and \ref close_stream.
*
- * Returns: an integer file descriptor
+ * \returns An integer file descriptor
*/
int get_stream_fd(Stream *st)
{
@@ -1672,6 +1692,11 @@ int get_stream_fd(Stream *st)
}
+/**
+ * \param st A \ref Stream
+ *
+ * Closes the stream
+ */
void close_stream(Stream *st)
{
free(st->audit_info);
@@ -1702,14 +1727,13 @@ int is_stream(const char *filename)
/**
- * write_command
- * @st: A %Stream
- * @argc: number of arguments
- * @argv: command-line arguments
+ * \param st A \ref Stream
+ * \param argc number of arguments
+ * \param argv command-line arguments
*
- * Writes the command line to @st. @argc and @argv should be exactly as were
+ * Writes the command line to \p st. \p argc and \p argv should be exactly as were
* given to main(). This should usually be called immediately after
- * open_stream_for_write().
+ * ref open_stream_for_write.
*/
void write_command(Stream *st, int argc, char *argv[])
{
@@ -1727,12 +1751,11 @@ void write_command(Stream *st, int argc, char *argv[])
/**
- * write_geometry_file
- * @st: A %Stream
- * @geom_filename: geomtry file name
+ * \param st A \ref Stream
+ * \param geom_filename geomtry file name
*
- * Writes the content of the geometry file to @st. This should usually be
- * called immediately after write_command().
+ * Writes the content of the geometry file to \p st. This should usually be
+ * called immediately after \ref write_command.
*/
void write_geometry_file(Stream *st, const char *geom_filename) {
@@ -1770,16 +1793,15 @@ void write_geometry_file(Stream *st, const char *geom_filename) {
/**
- * rewind_stream:
- * @st: A %Stream
+ * \param st A \ref Stream
*
- * Attempts to set the file pointer for @st to the start of the stream, so that
- * later calls to read_chunk() will repeat the sequence of chunks from the
+ * Attempts to set the file pointer for \p st to the start of the stream, so that
+ * later calls to \ref read_chunk will repeat the sequence of chunks from the
* start.
*
* Programs must not assume that this operation always succeeds!
*
- * Returns: non-zero if the stream could not be rewound.
+ * \returns Non-zero if the stream could not be rewound.
*/
int rewind_stream(Stream *st)
{