Merge pull request #43 from jakobnissen/flagdocs

Improve documentation of flag function

src/XAM.jl

@@ -4,6 +4,27 @@ export
     SAM,
     BAM
 
+"""
+    flag(record::Union{SAM.Record, BAM.Record})::UInt16
+
+Get the bitwise flags of `record`. The returned value is a `UInt16` of each flag
+being OR'd together. The possible flags are:
+
+    0x0001 template having multiple segments in sequencing
+    0x0002 each segment properly aligned according to the aligner
+    0x0004 segment unmapped
+    0x0008 next segment in the template unmapped
+    0x0010 SEQ being reverse complemented
+    0x0020 SEQ of the next segment in the template being reverse complemented
+    0x0040 the first segment in the template
+    0x0080 the last segment in the template
+    0x0100 secondary alignment
+    0x0200 not passing filters, such as platform/vendor quality controls
+    0x0400 PCR or optical duplicate
+    0x0800 supplementary alignment
+"""
+function flag end
+
 include("sam/sam.jl")
 include("bam/bam.jl")
 

src/bam/bam.jl

@@ -6,6 +6,7 @@ module BAM
 using BioGenerics
 using GenomicFeatures
 using XAM.SAM
+import ..XAM: flag
 
 import BGZFStreams
 import BioAlignments

src/bam/record.jl

@@ -128,11 +128,6 @@ end
 # Accessor Fuctions
 # -----------------
 
-"""
-    flag(record::Record)::UInt16
-
-Get the bitwise flag of `record`.
-"""
 function flag(record::Record)::UInt16
     checkfilled(record)
     return record.flag

src/sam/flags.jl

@@ -18,9 +18,13 @@ for (name, bits, doc) in [
         (:SUPPLEMENTARY, UInt16(0x800), "supplementary alignment"                                                   ),]
     @assert bits isa UInt16
     sym = Symbol("FLAG_", name)
-    doc = string(@sprintf("0x%04x: ", bits), doc)
+    docstring = """    $sym
+    SAM/BAM flag: $doc
+
+    See also: [`flag`](@ref)
+    """
     @eval begin
-        @doc $(doc) const $(sym) = $(bits)
+        @doc $(docstring) const $(sym) = $(bits)
     end
 end
 

src/sam/record.jl

@@ -150,11 +150,6 @@ end
 # Accessor Functions
 # ------------------
 
-"""
-    flag(record::Record)::UInt16
-
-Get the bitwise flag of `record`.
-"""
 function flag(record::Record)::UInt16
     checkfilled(record)
     return unsafe_parse_decimal(UInt16, record.data, record.flag)

src/sam/sam.jl

@@ -11,6 +11,7 @@ import BioGenerics.Exceptions: missingerror
 import BioGenerics.Automa: State
 import BioSequences
 import TranscodingStreams: TranscodingStreams, TranscodingStream
+import ..XAM: flag
 
 using Printf: @sprintf