* samtools-0.1.4-10 (r341)

[samtools.git] / sam.h

diff --git a/sam.h b/sam.h
index 082fe96b24913a2172b9b5b89036cb8fd91f1f0f..970cf2daee7ca49a95280bcf1431ae35ba8f223f 100644 (file)
--- a/sam.h
+++ b/sam.h
@@ -3,6 +3,24 @@
 
 #include "bam.h"
 
+/*!
+  @header
+
+  This file provides higher level of I/O routines and unifies the APIs
+  for SAM and BAM formats. These APIs are more convenient and
+  recommended.
+
+  @copyright Genome Research Ltd.
+ */
+
+/*! @typedef
+  @abstract SAM/BAM file handler
+  @field  type    type of the handler; bit 1 for BAM and bit 2 for reading
+  @field  bam   BAM file handler; valid if (type&1) == 1
+  @field  tamr  SAM file handler for reading; valid if type == 2
+  @field  tamw  SAM file handler for writing; valid if type == 0
+  @field  header  header struct
+ */
 typedef struct {
        int type;
        union {
@@ -17,12 +35,57 @@ typedef struct {
 extern "C" {
 #endif
 
-       // mode can be: r/w/rb/wb. On writing, aux points to bam_header_t; on reading, aux points to the name of fn_list for SAM
+       /*!
+         @abstract     Open a SAM/BAM file
+
+         @param fn SAM/BAM file name; "-" is recognized as stdin (for
+         reading) or stdout (for writing).
+
+         @param mode open mode /[rw](b?)(u?)(h?)/: 'r' for reading, 'w' for
+         writing, 'b' for BAM I/O, 'u' for uncompressed BAM output and 'h'
+         for outputing header in SAM. If 'b' present, it must immediately
+         follow 'r' or 'w'. Valid modes are "r", "w", "wh", "rb", "wb" and
+         "wbu" exclusively.
+
+         @param aux auxiliary data; if mode[0]=='w', aux points to
+         bam_header_t; if strcmp(mode, "rb")==0 and @SQ header lines in SAM
+         are absent, aux points the file name of the list of the reference;
+         aux is not used otherwise.
+
+         @return       SAM/BAM file handler
+        */
        samfile_t *samopen(const char *fn, const char *mode, const void *aux);
+
+       /*!
+         @abstract     Close a SAM/BAM handler
+         @param  fp    file handler to be closed
+        */
        void samclose(samfile_t *fp);
+
+       /*!
+         @abstract     Read one alignment
+         @param  fp    file handler
+         @param  b     alignment
+         @return       bytes read
+        */
        int samread(samfile_t *fp, bam1_t *b);
+
+       /*!
+         @abstract     Write one alignment
+         @param  fp    file handler
+         @param  b     alignment
+         @return       bytes written
+        */
        int samwrite(samfile_t *fp, const bam1_t *b);
-       int sampileup(samfile_t *fp, int mask, int min_mapQ, bam_pileup_f func, void *func_data);
+
+       /*!
+         @abstract     Get the pileup for a whole alignment file
+         @param  fp    file handler
+         @param  mask  mask transferred to bam_plbuf_set_mask()
+         @param  func  user defined function called in the pileup process
+         #param  data  user provided data for func()
+        */
+       int sampileup(samfile_t *fp, int mask, bam_pileup_f func, void *data);
 
 #ifdef __cplusplus
 }