adding some more docs

pybwa/libbwaaln.pyx

@@ -33,6 +33,7 @@ cdef class BwaAlnOptions:
         free(self._delegate)
 
     cdef gap_opt_t* gap_opt(self):
+        """Returns the options struct to use with the bwa C library methods"""
         return self._delegate
 
     property max_mismatches:
@@ -138,6 +139,14 @@ cdef class BwaAln:
     cdef BwaIndex _index
 
     def __init__(self, prefix: str | Path | None = None, index: BwaIndex | None = None):
+        """Constructs the :code:`bwa aln` aligner.
+
+        One of `prefix` or `index` must be specified.
+
+        Args:
+            prefix: the path prefix for the BWA index (typically a FASTA)
+            index: the index to use
+        """
         if prefix is not None:
             assert Path(prefix).exists()
             self._index = BwaIndex(prefix=prefix)
@@ -148,7 +157,6 @@ cdef class BwaAln:
 
         bwase_initialize()
 
-    # TODO: a list of records...
     def align(self, queries: List[FastxRecord] | List[str], opt: BwaAlnOptions | None = None) -> List[AlignedSegment]:
         """Align one or more queries with `bwa aln`.
 
@@ -157,7 +165,8 @@ cdef class BwaAln:
             opt: the alignment options, or None to use the default options
 
         Returns:
-            one alignment per query
+            one alignment (:class:`~pysam.AlignedSegment`) per query
+            :code:`List[List[AlignedSegment]]`.
         """
         if len(queries) == 0:
             return []

pybwa/libbwaindex.pyx

@@ -41,7 +41,7 @@ cdef class BwaIndex:
     with :code:`samtools dict <fasta>`).
 
     Args:
-        prefix (str | Path): the path prefix for teh BWA index
+        prefix (str | Path): the path prefix for the BWA index (typically a FASTA)
         bwt (bool): load the BWT (FM-index)
         bns (bool): load the BNS (reference sequence metadata)
         pac (bool): load the PAC (the actual 2-bit encoded reference sequences with 'N' converted to a

pybwa/libbwamem.pyx

@@ -38,7 +38,9 @@ cdef class BwaMemOptions:
     def _assert_not_finalized(self, attr_name: str) -> None:
         """Raises an AttributeError if the options have been finalized.
 
-        This is used in each setter below, as cython does not support decorating properties.
+        This is used in each setter below to enforce that setters are not used after
+         :meth:`~pybwa.BwaMemOptions.finalize` is called.  This could be a property decorator,
+         but cython does not support decorating properties.
         """
         if self._finalized:
             raise AttributeError(f"can't set attribute: {attr_name}")
@@ -547,6 +549,14 @@ cdef class BwaMem:
     cdef BwaIndex _index
 
     def __init__(self, prefix: str | Path | None = None, index: BwaIndex | None = None):
+        """Constructs the :code:`bwa mem` aligner.
+
+        One of `prefix` or `index` must be specified.
+
+        Args:
+            prefix: the path prefix for the BWA index (typically a FASTA)
+            index: the index to use
+        """
         if prefix is not None:
             assert Path(prefix).exists()
             self._index = BwaIndex(prefix=prefix)
@@ -564,7 +574,8 @@ cdef class BwaMem:
             opt: the alignment options, or None to use the default options
 
         Returns:
-            one alignment per query
+            a list of alignments (:class:`~pysam.AlignedSegment`) per query
+            :code:`List[List[AlignedSegment]]`.
         """
         if opt is None:
             opt = BwaMemOptions().finalize()