03b7b3bc8338dc0bf9ba3aa4e2d90b232fb53b2b
kent
  Tue Mar 4 12:25:40 2014 -0800
Adding nice usage comment to this C interface to bigBed files.
diff --git src/inc/bigBed.h src/inc/bigBed.h
index 77335e3..8031299 100644
--- src/inc/bigBed.h
+++ src/inc/bigBed.h
@@ -1,19 +1,51 @@
 /* bigBed - interface to binary file with bed-style values (that is a bunch of
  * possibly overlapping regions.
  *
- * This shares a lot with the bigWig module. */
+ * This shares a lot with the bigWig module. 
+ *
+ * Most of the functions here are concerned with reading bigBed files.  There's
+ * two common things you want to do with a bigBed,  either stream through everything in it,
+ * or just read the parts that overlap a interval within the genome.  The files
+ * are optimized for interval queries, but streaming through them is not difficult either.
+ * 
+ * To query an interval:
+ *    struct bbiFile *bbi = bigBedFileOpen(fileName);
+ *    struct lm *lm = lmInit(0); // Memory pool to hold returned list
+ *    struct bigBedInterval *list = bigBedIntervalQuery(bbi, chrom, start, end, 0, lm);
+ *    struct bigBedInterval *el;
+ *    for (el = list; el != NULL; el = el->next)
+ *        // do something involving chrom, el->start, el->end
+ *    lmCleanup(&lm);         // typically do this after each query
+ *    bigBedFileClose(&bbi);  // typically only do this when finished all queries
+ *
+ * To stream through whole file
+ *    struct bbiFile *bbi = bigBedFileOpen(fileName);
+ *    struct bbiChromInfo *chrom, *chromList = bbiChromList(bbi);
+ *    for (chrom = chromList; chrom != NULL; chrom = chrom->next)
+ *        {
+ *        struct lm *lm = lmInit(0);
+ *        struct bigBedInterval *list = bigBedIntervalQuery(bbi,chrom->name,0,chrom->size,0,lm);
+ *        struct bigBedInterval *el;
+ *        for (el = list; el != NULL; el = el->next)
+ *            // do something involving chrom, el->start, el->end
+ *        lmCleanup(&lm);
+ *        }
+ *    bigBedFileClose(&bbi);
+ *
+ * The processes for streaming through or doing interval queries on a bigWig file are very 
+ * similar. */
 
 #ifndef BIGBED_H
 #define BIGBED_H
 
 #include "asParse.h"
 
 #ifndef BBIFILE
 #include "bbiFile.h"
 #endif
 
 struct bigBedInterval
 /* A partially parsed out bed record plus some extra fields.  Use this directly
  * or convert it to an array of characters with bigBedIntervalToRow. */
     {
     struct bigBedInterval *next;	/* Next in list. */