#17 Write docstrings

cljam.cigar, cljam.common, cljam.dict, cljam.fasta, cljam.fasta-indexer, cljam.io, cljam.lsb, cljam.sequence, and cljam.sorter

src/cljam/cigar.clj

@@ -1,7 +1,8 @@
-(ns cljam.cigar)
+(ns cljam.cigar
+  "Parser of CIGAR strings.")
 
 (defn parse
-  "Parses CIGAR text, returns seq of lengths and operations."
+  "Parses CIGAR string, returning a sequence of lengths and operations."
   [^String s]
   (for [[_ n op] (re-seq #"([0-9]*)([MIDNSHP=X])" s)]
     [(Integer/parseInt n) (first op)]))

src/cljam/common.clj

@@ -1,3 +1,4 @@
-(ns cljam.common)
+(ns cljam.common
+  "Common vars.")
 
 (def version "SAM format version" "1.4")

src/cljam/dict.clj

@@ -1,4 +1,6 @@
 (ns cljam.dict
+  "Alpha - subject to change.
+  Generator of a FASTA sequence dictionary file."
   (:require [clojure.java.io :refer [file writer]]
             [clojure.string :as str]
             [cljam.common :refer [version]]

src/cljam/fasta.clj

@@ -1,4 +1,6 @@
 (ns cljam.fasta
+  "Alpha - subject to change.
+  Reader of a FASTA format file."
   (:refer-clojure :exclude [read slurp])
   (:import [java.io RandomAccessFile Closeable]))
 

src/cljam/fasta_indexer.clj

@@ -1,5 +1,6 @@
 (ns cljam.fasta-indexer
-  "Indexer of FASTA."
+  "Alpha - subject to change.
+  Indexer of FASTA."
   (:require [cljam.fasta :as fasta]
             [cljam.fasta-index.writer :as fai-writer]))
 

src/cljam/io.clj

@@ -1,19 +1,21 @@
-(ns cljam.io)
-
-;;; Protocol
+(ns cljam.io
+  "Protocols of SAM/BAM reader.")
 
 (defprotocol ISAMReader
-  (reader-path [this])
-  (read-header [this])
-  (read-refs [this])
-  (read-alignments [this option])
+  (reader-path [this] "Returns the file's absolute path.")
+  (read-header [this] "Returns header of the SAM/BAM file.")
+  (read-refs [this] "Returns references of the SAM/BAM file.")
+  (read-alignments [this option]
+    "Reads alignments of the SAM/BAM file, returning the alignments as a lazy
+    sequence.")
   (read-blocks [this])
   (read-coordinate-blocks [this]))
 
 (defprotocol ISAMWriter
-  (writer-path [this])
-  (write-header [this header])
-  (write-refs [this header])
-  (write-alignments [this alignments header])
+  (writer-path [this] "Returns the file's absolute path.")
+  (write-header [this header] "Writes header to the SAM/BAM file.")
+  (write-refs [this header] "Writes references to the SAM/BAM file.")
+  (write-alignments [this alignments header]
+    "Writes alignments to the SAM/BAM file.")
   (write-blocks [this blocks])
   (write-coordinate-blocks [this blocks]))

src/cljam/lsb.clj

@@ -1,19 +1,25 @@
 (ns cljam.lsb
+  "Reading/writing functions of stream and buffer for little-endian data."
   (:refer-clojure :exclude [read-string])
   (:require [cljam.util :refer [string->bytes bytes->string]])
   (:import [java.io DataInputStream DataOutputStream EOFException]
            [java.nio ByteBuffer ByteOrder]))
 
 (defn ^ByteBuffer gen-byte-buffer
+  "Generates a new `java.nio.ByteBuffer` instance with little-endian byte order.
+  The default buffer size is 8."
   ([]
      (.order (ByteBuffer/allocate 8) ByteOrder/LITTLE_ENDIAN))
   ([size]
      (.order (ByteBuffer/allocate size) ByteOrder/LITTLE_ENDIAN)))
 
-;;; skip
+;; Skip
+;; ----
 
 (defprotocol Skippable
-  (skip [this n]))
+  "Provides skipping data feature. Note that this feature is implemented by
+  protocol instead of multimethods for performance."
+  (skip [this n] "Skip over n bytes of data, discarding the skipped bytes."))
 
 (extend-protocol Skippable
   DataInputStream
@@ -25,10 +31,14 @@
     (.position bb (+ (.position bb) n))
     nil))
 
-;;; reading
+;; Reading
+;; -------
 
 (defprotocol BytesReadble
-  (read-bytes [this l] [this buffer offset l]))
+  "Provides bytes reading feature. Note that this feature is implemented by
+  Protocol instead of multimethods for performance."
+  (read-bytes [this len] [this buffer offset len]
+    "Reads up to len bytes of data."))
 
 (extend-protocol BytesReadble
   DataInputStream
@@ -120,7 +130,8 @@
     (.get bb)
     (bytes->string ba)))
 
-;;; writing
+;; Writing
+;; -------
 
 (defn write-char
   [^DataOutputStream w b]

src/cljam/sequence.clj

@@ -1,4 +1,5 @@
 (ns cljam.sequence
+  "Parser of genome sequence strings."
   (:require [cljam.cigar :as cgr]))
 
 (defn- parse-seq [seq* cigar]

src/cljam/sorter.clj

@@ -1,4 +1,5 @@
 (ns cljam.sorter
+  "Sorter of SAM/BAM format alignments."
   (:require [clojure.java.io :refer [file]]
             [clojure.string :as str]
             (cljam [sam :as sam]
@@ -14,9 +15,8 @@
 (def order-coordinate :coordinate)
 (def order-queryname :queryname)
 
-;;
-;; coordinate sorter
-;;
+;; Coordinate sorter
+;; -----------------
 
 (defn- replace-header [hdr vn so]
   (conj hdr {:HD {:VN vn, :SO so}}))
@@ -38,9 +38,8 @@
                                     (map :name (sam-util/make-refs (io/read-header rdr)))))]
     (sort (partial compare-key-pos ref-map) (io/read-coordinate-blocks rdr))))
 
-;;
-;; queryname sorter
-;;
+;; Queryname sorter
+;; ----------------
 
 ;; (defn- compkey-qname [hdr aln]
 ;;   [(.indexOf ^List (map :name (sam-util/make-refs hdr)) (:rname aln))
@@ -53,9 +52,8 @@
   ;;      (assoc sam :alignments))
   )
 
-;;
 ;; split/merge
-;;
+;; -----------
 
 (defn gen-cache-filename
   [prefix i]
@@ -128,9 +126,8 @@
       (clean (name-fn i))
       (clean (sorted-name-fn i)))))
 
-;;
-;; sorter
-;;
+;; Sorter
+;; ------
 
 (defn sort-by-pos [rdr wtr]
   (let [filename (.getName (file (io/reader-path rdr)))