Mention _destroy function in each init function's documentation (PR #992

)

Add a note about the corresponding *_destroy()/*_free() function to the
API doxygen for each function that allocates a structure and returns it
with the expectation that the caller will eventually free it.

htslib/cram.h

@@ -247,6 +247,9 @@ int cram_copy_slice(cram_fd *in, cram_fd *out, int32_t num_slice);
  * @return
  * Returns block pointer on success;
  *         NULL on failure
+ *
+ * The cram_block struct returned by a successful call should be freed
+ * via cram_free_block() when it is no longer needed.
  */
 HTSLIB_EXPORT
 cram_block *cram_new_block(enum cram_content_type content_type,
@@ -257,6 +260,9 @@ cram_block *cram_new_block(enum cram_content_type content_type,
  * @return
  * Returns cram_block pointer on success;
  *         NULL on failure
+ *
+ * The cram_block struct returned by a successful call should be freed
+ * via cram_free_block() when it is no longer needed.
  */
 HTSLIB_EXPORT
 cram_block *cram_read_block(cram_fd *fd);
@@ -312,6 +318,9 @@ int cram_compress_block(cram_fd *fd, cram_block *b, cram_metrics *metrics,
  * @return
  * Returns cram_container ptr on success;
  *         NULL on failure
+ *
+ * The cram_container struct returned by a successful call should be freed
+ * via cram_free_container() when it is no longer needed.
  */
 HTSLIB_EXPORT
 cram_container *cram_new_container(int nrec, int nslice);
@@ -323,6 +332,9 @@ void cram_free_container(cram_container *c);
  * @return
  * Returns cram_container on success;
  *         NULL on failure or no container left (fd->err == 0).
+ *
+ * The cram_container struct returned by a successful call should be freed
+ * via cram_free_container() when it is no longer needed.
  */
 HTSLIB_EXPORT
 cram_container *cram_read_container(cram_fd *fd);

htslib/faidx.h

@@ -121,6 +121,9 @@ The bgzip index is only needed if fn is compressed.
 
 If (flags & FAI_CREATE) is true, the index files will be built using
 fai_build3() if they are not already present.
+
+The struct returned by a successful call should be freed via fai_destroy()
+when it is no longer needed.
 */
 HTSLIB_EXPORT
 faidx_t *fai_load3(const char *fn, const char *fnfai, const char *fngzi,
@@ -149,6 +152,9 @@ The bgzip index is only needed if fn is compressed.
 
 If (flags & FAI_CREATE) is true, the index files will be built using
 fai_build3() if they are not already present.
+
+The struct returned by a successful call should be freed via fai_destroy()
+when it is no longer needed.
 */
 HTSLIB_EXPORT
 faidx_t *fai_load3_format(const char *fn, const char *fnfai, const char *fngzi,

htslib/hts.h

@@ -704,6 +704,9 @@ typedef hts_itr_t hts_itr_multi_t;
     @param min_shift  Number of bits for the minimal interval
     @param n_lvls     Number of levels in the binning index
     @return An initialised hts_idx_t struct on success; NULL on failure
+
+The struct returned by a successful call should be freed via hts_idx_destroy()
+when it is no longer needed.
 */
 HTSLIB_EXPORT
 hts_idx_t *hts_idx_init(int n, int fmt, uint64_t offset0, int min_shift, int n_lvls);
@@ -837,6 +840,9 @@ hts_idx_t *hts_idx_load2(const char *fn, const char *fnidx);
 
         HTS_IDX_SAVE_REMOTE   Save a local copy of any remote indexes
         HTS_IDX_SILENT_FAIL   Fail silently if the index is not present
+
+    The index struct returned by a successful call should be freed
+    via hts_idx_destroy() when it is no longer needed.
 */
 HTSLIB_EXPORT
 hts_idx_t *hts_idx_load3(const char *fn, const char *fnidx, int fmt, int flags);
@@ -1036,6 +1042,9 @@ const char *hts_parse_region(const char *s, int *tid, hts_pos_t *beg,
     @param end      End of region
     @param readrec  Callback to read a record from the input file
     @return An iterator on success; NULL on failure
+
+    The iterator struct returned by a successful call should be freed
+    via hts_itr_destroy() when it is no longer needed.
  */
 HTSLIB_EXPORT
 hts_itr_t *hts_itr_query(const hts_idx_t *idx, int tid, hts_pos_t beg, hts_pos_t end, hts_readrec_func *readrec);
@@ -1057,6 +1066,9 @@ typedef hts_itr_t *hts_itr_query_func(const hts_idx_t *idx, int tid, hts_pos_t b
                      start and end position
     @param readrec   Callback to read a record from the input file
     @return An iterator on success; NULL on error
+
+    The iterator struct returned by a successful call should be freed
+    via hts_itr_destroy() when it is no longer needed.
  */
 HTSLIB_EXPORT
 hts_itr_t *hts_itr_querys(const hts_idx_t *idx, const char *reg, hts_name2id_f getid, void *hdr, hts_itr_query_func *itr_query, hts_readrec_func *readrec);
@@ -1105,6 +1117,9 @@ int hts_itr_multi_cram(const hts_idx_t *idx, hts_itr_t *iter);
     @param seek         Callback to seek in the input file
     @param tell         Callback to return current input file location
     @return An iterator on success; NULL on failure
+
+    The iterator struct returned by a successful call should be freed
+    via hts_itr_destroy() when it is no longer needed.
  */
 HTSLIB_EXPORT
 hts_itr_t *hts_itr_regions(const hts_idx_t *idx, hts_reglist_t *reglist, int count, hts_name2id_f getid, void *hdr, hts_itr_multi_query_func *itr_specific, hts_readrec_func *readrec, hts_seek_func *seek, hts_tell_func *tell);
@@ -1125,6 +1140,9 @@ int hts_itr_multi_next(htsFile *fd, hts_itr_t *iter, void *r);
     @param hdr       Header for the sam/bam/cram file
     @param getid     Callback to convert target names to target ids.
     @return  A region list on success, NULL on failure
+
+    The hts_reglist_t struct returned by a successful call should be freed
+    via hts_reglist_free() when it is no longer needed.
  */
 HTSLIB_EXPORT
 hts_reglist_t *hts_reglist_create(char **argv, int argc, int *r_count, void *hdr,  hts_name2id_f getid);

htslib/regidx.h

@@ -142,6 +142,9 @@ int regidx_parse_vcf(const char*,char**,char**,hts_pos_t*,hts_pos_t*,void*,void*
  *  @param usr:    optional user data passed to regidx_parse_f
  *
  *  Returns index on success or NULL on error.
+ *
+ *  The regidx_t index struct returned by a successful call should be freed
+ *  via regidx_destroy() when it is no longer needed.
  */
 HTSLIB_EXPORT
 regidx_t *regidx_init(const char *fname, regidx_parse_f parsef, regidx_free_f freef, size_t payload_size, void *usr);
@@ -200,6 +203,10 @@ int regidx_nregs(regidx_t *idx);
  *                  with regitr_loop. If only regitr_overlap is called, NULL
  *                  can be given.
  *
+ *                  The regitr_t struct returned by a successful regitr_init()
+ *                  call should be freed via regitr_destroy() when it is no
+ *                  longer needed.
+ *
  *  regitr_reset() - initialize an iterator for a repeated regitr_loop cycle.
  *                  Not required with regitr_overlap.
  */

htslib/sam.h

@@ -327,6 +327,9 @@ typedef struct {
 /*!
  *
  * @return  A valid pointer to new header on success, NULL on failure
+ *
+ * The sam_hdr_t struct returned by a successful call should be freed
+ * via sam_hdr_destroy() when it is no longer needed.
  */
 HTSLIB_EXPORT
 sam_hdr_t *sam_hdr_init(void);
@@ -338,6 +341,9 @@ sam_hdr_t *sam_hdr_init(void);
  *
  * This function only works with BAM files.  It is usually better to use
  * sam_hdr_read(), which works on SAM, BAM and CRAM files.
+ *
+ * The sam_hdr_t struct returned by a successful call should be freed
+ * via sam_hdr_destroy() when it is no longer needed.
  */
 HTSLIB_EXPORT
 sam_hdr_t *bam_hdr_read(BGZF *fp);
@@ -363,6 +369,9 @@ void sam_hdr_destroy(sam_hdr_t *h);
 /// Duplicate a header structure.
 /*!
  * @return  A valid pointer to new header on success, NULL on failure
+ *
+ * The sam_hdr_t struct returned by a successful call should be freed
+ * via sam_hdr_destroy() when it is no longer needed.
  */
 HTSLIB_EXPORT
 sam_hdr_t *sam_hdr_dup(const sam_hdr_t *h0);
@@ -383,6 +392,9 @@ typedef htsFile samFile;
  * @return A populated sam_hdr_t structure on success; NULL on failure.
  * @note The text field of the returned header will be NULL, and the l_text
  * field will be zero.
+ *
+ * The sam_hdr_t struct returned by a successful call should be freed
+ * via sam_hdr_destroy() when it is no longer needed.
  */
 HTSLIB_EXPORT
 sam_hdr_t *sam_hdr_parse(size_t l_text, const char *text);
@@ -391,6 +403,9 @@ sam_hdr_t *sam_hdr_parse(size_t l_text, const char *text);
 /*!
  * @param fp    Pointer to a SAM, BAM or CRAM file handle
  * @return  A populated sam_hdr_t struct on success; NULL on failure.
+ *
+ * The sam_hdr_t struct returned by a successful call should be freed
+ * via sam_hdr_destroy() when it is no longer needed.
  */
 HTSLIB_EXPORT
 sam_hdr_t *sam_hdr_read(samFile *fp);
@@ -814,11 +829,14 @@ void sam_hdr_incr_ref(sam_hdr_t *h);
 /// Create a new bam1_t alignment structure
 /**
    @return An empty bam1_t structure on success, NULL on failure
+
+   The bam1_t struct returned by a successful call should be freed
+   via bam_destroy1() when it is no longer needed.
  */
 HTSLIB_EXPORT
 bam1_t *bam_init1(void);
 
-/// Destory a bam1_t structure
+/// Destroy a bam1_t structure
 /**
    @param b  structure to destroy
 
@@ -969,6 +987,9 @@ bam1_t *bam_copy1(bam1_t *bdst, const bam1_t *bsrc) HTS_RESULT_USED;
 /**
    @param bsrc  Source alignment record
    @return Pointer to a new alignment record on success; NULL on failure
+
+   The bam1_t struct returned by a successful call should be freed
+   via bam_destroy1() when it is no longer needed.
  */
 HTSLIB_EXPORT
 bam1_t *bam_dup1(const bam1_t *bsrc);
@@ -1113,6 +1134,9 @@ The @p flags parameter can be set to a combination of the following values:
 
 Note that HTS_IDX_SAVE_REMOTE has no effect for remote CRAM indexes.  They
 are always downloaded and never cached locally.
+
+The index struct returned by a successful call should be freed
+via hts_idx_destroy() when it is no longer needed.
 */
 HTSLIB_EXPORT
 hts_idx_t *sam_index_load3(htsFile *fp, const char *fn, const char *fnidx, int flags);
@@ -1591,6 +1615,9 @@ typedef struct __bam_mplp_t *bam_mplp_t;
      *  @func:      see mplp_func in bam_plcmd.c in samtools for an example. Expected return
      *              status: 0 on success, -1 on end, < -1 on non-recoverable errors
      *  @data:      user data to pass to @func
+     *
+     *  The struct returned by a successful call should be freed
+     *  via bam_plp_destroy() when it is no longer needed.
      */
     HTSLIB_EXPORT
     bam_plp_t bam_plp_init(bam_plp_auto_f func, void *data);
@@ -1650,8 +1677,13 @@ typedef struct __bam_mplp_t *bam_mplp_t;
     HTSLIB_EXPORT
     int bam_plp_insertion(const bam_pileup1_t *p, kstring_t *ins, int *del_len) HTS_RESULT_USED;
 
+    /// Create a new bam_mplp_t structure
+    /** The struct returned by a successful call should be freed
+     *  via bam_mplp_destroy() when it is no longer needed.
+     */
     HTSLIB_EXPORT
     bam_mplp_t bam_mplp_init(int n, bam_plp_auto_f func, void **data);
+
     /// Set up mpileup overlap detection
     /**
      * @param iter    mpileup iterator

htslib/synced_bcf_reader.h

@@ -185,11 +185,15 @@ typedef struct
 }
 bcf_srs_t;
 
-/** Init bcf_srs_t struct */
+/** Allocate and initialize a bcf_srs_t struct.
+ *
+ *  The bcf_srs_t struct returned by a successful call should be freed
+ *  via bcf_sr_destroy() when it is no longer needed.
+ */
 HTSLIB_EXPORT
 bcf_srs_t *bcf_sr_init(void);
 
-/** Destroy  bcf_srs_t struct */
+/** Destroy a bcf_srs_t struct */
 HTSLIB_EXPORT
 void bcf_sr_destroy(bcf_srs_t *readers);
 
@@ -323,6 +327,9 @@ int bcf_sr_set_regions(bcf_srs_t *readers, const char *regions, int is_file);
  *              supply 'from' in place of 'to'. When 'to' is negative, first
  *              abs(to) will be attempted and if that fails, 'from' will be used
  *              instead.
+ *
+ *  The bcf_sr_regions_t struct returned by a successful call should be freed
+ *  via bcf_sr_regions_destroy() when it is no longer needed.
  */
 HTSLIB_EXPORT
 bcf_sr_regions_t *bcf_sr_regions_init(const char *regions, int is_file, int chr, int from, int to);

htslib/tbx.h

@@ -70,6 +70,10 @@ extern const tbx_conf_t tbx_conf_gff, tbx_conf_bed, tbx_conf_psltbl, tbx_conf_sa
     HTSLIB_EXPORT
     int tbx_readrec(BGZF *fp, void *tbxv, void *sv, int *tid, hts_pos_t *beg, hts_pos_t *end);
 
+/// Build an index of the lines in a BGZF-compressed file
+/** The index struct returned by a successful call should be freed
+    via tbx_destroy() when it is no longer needed.
+*/
     HTSLIB_EXPORT
     tbx_t *tbx_index(BGZF *fp, int min_shift, const tbx_conf_t *conf);
 /*
@@ -118,6 +122,9 @@ extern const tbx_conf_t tbx_conf_gff, tbx_conf_bed, tbx_conf_psltbl, tbx_conf_sa
 
         HTS_IDX_SAVE_REMOTE   Save a local copy of any remote indexes
         HTS_IDX_SILENT_FAIL   Fail silently if the index is not present
+
+    The index struct returned by a successful call should be freed
+    via tbx_destroy() when it is no longer needed.
 */
     HTSLIB_EXPORT
     tbx_t *tbx_index_load3(const char *fn, const char *fnidx, int flags);

htslib/thread_pool.h

@@ -100,6 +100,9 @@ typedef struct hts_tpool_result hts_tpool_result;
  *
  * Returns pool pointer on success;
  *         NULL on failure
+ *
+ * The hts_tpool struct returned by a successful call should be freed
+ * via hts_tpool_destroy() when it is no longer needed.
  */
 HTSLIB_EXPORT
 hts_tpool *hts_tpool_init(int n);
@@ -298,6 +301,9 @@ void *hts_tpool_result_data(hts_tpool_result *r);
  *
  * Results hts_tpool_process pointer on success;
  *         NULL on failure
+ *
+ * The hts_tpool_process struct returned by a successful call should be freed
+ * via hts_tpool_process_destroy() when it is no longer needed.
  */
 HTSLIB_EXPORT
 hts_tpool_process *hts_tpool_process_init(hts_tpool *p, int qsize, int in_only);