From a72fcf47cbfef82ee296ca28dff95e2a8ef7ad2b Mon Sep 17 00:00:00 2001
From: Jakob Nybo Nissen <jakobnybonissen@gmail.com>
Date: Fri, 22 Oct 2021 10:48:07 +0200
Subject: [PATCH] Improve documentation of flag function

---
 src/XAM.jl        | 21 +++++++++++++++++++++
 src/bam/bam.jl    |  1 +
 src/bam/record.jl |  5 -----
 src/sam/flags.jl  |  8 ++++++--
 src/sam/record.jl |  5 -----
 src/sam/sam.jl    |  1 +
 6 files changed, 29 insertions(+), 12 deletions(-)

diff --git a/src/XAM.jl b/src/XAM.jl
index 8609747..2c5bad1 100644
--- a/src/XAM.jl
+++ b/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")
 
diff --git a/src/bam/bam.jl b/src/bam/bam.jl
index 6fd1174..b3591d7 100644
--- a/src/bam/bam.jl
+++ b/src/bam/bam.jl
@@ -6,6 +6,7 @@ module BAM
 using BioGenerics
 using GenomicFeatures
 using XAM.SAM
+import ..XAM: flag
 
 import BGZFStreams
 import BioAlignments
diff --git a/src/bam/record.jl b/src/bam/record.jl
index 61a5c65..b545600 100644
--- a/src/bam/record.jl
+++ b/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
diff --git a/src/sam/flags.jl b/src/sam/flags.jl
index 0b629d1..7b476fa 100644
--- a/src/sam/flags.jl
+++ b/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
 
diff --git a/src/sam/record.jl b/src/sam/record.jl
index 7dde515..dc0c43d 100644
--- a/src/sam/record.jl
+++ b/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)
diff --git a/src/sam/sam.jl b/src/sam/sam.jl
index 97b8a05..fcd0821 100644
--- a/src/sam/sam.jl
+++ b/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