X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=src%2Fapi%2FSamHeader.cpp;h=7a69162027a07fca6a2aa641048481e3d6245498;hb=8c80d760637f8df39262683cd2570f0589423d36;hp=5134630a7d3a65b11e7e0fe07afe0357ed74e328;hpb=577b6032aa3d85616047c8aba6061dd8dad20cfc;p=bamtools.git

diff --git a/src/api/SamHeader.cpp b/src/api/SamHeader.cpp
index 5134630..7a69162 100644
--- a/src/api/SamHeader.cpp
+++ b/src/api/SamHeader.cpp
@@ -3,10 +3,10 @@
 // Marth Lab, Department of Biology, Boston College
 // All rights reserved.
 // ---------------------------------------------------------------------------
-// Last modified: 23 December 2010 (DB)
+// Last modified: 4 March 2011 (DB)
 // ---------------------------------------------------------------------------
-// Provides functionality for querying/manipulating SAM header data
-// **************************************************************************
+// Provides direct read/write access to the SAM header data fields.
+// ***************************************************************************
 
 #include <api/SamHeader.h>
 #include <api/internal/SamFormatParser_p.h>
@@ -16,8 +16,47 @@ using namespace BamTools;
 using namespace BamTools::Internal;
 using namespace std;
 
-// ctor
-SamHeader::SamHeader(const string& headerText)
+/*! \struct BamTools::SamHeader
+    \brief Represents the SAM-formatted text header that is part of the BAM file header.
+
+    Provides direct read/write access to the SAM header data fields.
+
+    \sa http://samtools.sourceforge.net/SAM-1.3.pdf
+*/
+/*! \var SamHeader::Version
+    \brief corresponds to \@HD VN:\<Version\>
+*/
+/*! \var SamHeader::SortOrder
+    \brief corresponds to \@HD SO:\<SortOrder\>
+*/
+/*! \var SamHeader::GroupOrder
+    \brief corresponds to \@HD GO:\<GroupOrder\>
+*/
+/*! \var SamHeader::Sequences
+    \brief corresponds to \@SQ entries
+    \sa SamSequence, SamSequenceDictionary
+*/
+/*! \var SamHeader::ReadGroups
+    \brief corresponds to \@RG entries
+    \sa SamReadGroup, SamReadGroupDictionary
+*/
+/*! \var SamHeader::ProgramName
+    \brief corresponds to \@PG ID:\<ProgramName\>
+*/
+/*! \var SamHeader::ProgramVersion
+    \brief corresponds to \@PG VN:\<ProgramVersion\>
+*/
+/*! \var SamHeader::ProgramCommandLine
+    \brief corresponds to \@PG CL:\<ProgramCommandLine\>
+*/
+/*! \var SamHeader::Comments
+    \brief corresponds to \@CO entries
+*/
+
+/*! \fn SamHeader::SamHeader(const std::string& headerText = "")
+    \brief constructor
+*/
+SamHeader::SamHeader(const std::string& headerText)
     : Version("")
     , SortOrder("")
     , GroupOrder("")
@@ -29,7 +68,9 @@ SamHeader::SamHeader(const string& headerText)
     parser.Parse(headerText);
 }
 
-// copy ctor
+/*! \fn SamHeader::SamHeader(const SamHeader& other)
+    \brief copy constructor
+*/
 SamHeader::SamHeader(const SamHeader& other)
     : Version(other.Version)
     , SortOrder(other.SortOrder)
@@ -41,11 +82,14 @@ SamHeader::SamHeader(const SamHeader& other)
     , ProgramCommandLine(other.ProgramCommandLine)
 { }
 
-// dtor
-SamHeader::~SamHeader(void) {
-    Clear();
-}
+/*! \fn SamHeader::~SamHeader(void)
+    \brief destructor
+*/
+SamHeader::~SamHeader(void) { }
 
+/*! \fn void SamHeader::Clear(void)
+    \brief Clears all header contents.
+*/
 void SamHeader::Clear(void) {
     Version.clear();
     SortOrder.clear();
@@ -58,69 +102,102 @@ void SamHeader::Clear(void) {
     Comments.clear();
 }
 
-void SamHeader::SetHeaderText(const std::string& headerText) {
-
-    // clear prior data
-    Clear();
-
-    // parse header text into data
-    SamFormatParser parser(*this);
-    parser.Parse(headerText);
-}
-
-// retrieve the SAM header, with any local modifications
-string SamHeader::ToString(void) const {
-    SamFormatPrinter printer(*this);
-    return printer.ToString();
-}
-
-// query if header contains @HD ID:<Version>
+/*! \fn bool SamHeader::HasVersion(void) const
+    \brief Returns \c true if header contains \@HD ID:\<Version\>
+*/
 bool SamHeader::HasVersion(void) const {
     return (!Version.empty());
 }
 
-// query if header contains @HD SO:<SortOrder>
+/*! \fn bool SamHeader::HasSortOrder(void) const
+    \brief Returns \c true if header contains \@HD SO:\<SortOrder\>
+*/
 bool SamHeader::HasSortOrder(void) const {
     return (!SortOrder.empty());
 }
 
-// query if header contains @HD GO:<GroupOrder>
+/*! \fn bool SamHeader::HasGroupOrder(void) const
+    \brief Returns \c true if header contains \@HD GO:\<GroupOrder\>
+*/
 bool SamHeader::HasGroupOrder(void) const {
     return (!GroupOrder.empty());
 }
 
-// query if header contains @SQ entries
+/*! \fn bool SamHeader::HasSequences(void) const
+    \brief Returns \c true if header contains any \@SQ entries
+*/
 bool SamHeader::HasSequences(void) const {
     return (!Sequences.IsEmpty());
 }
 
-// query if header contains @RG entries
+/*! \fn bool SamHeader::HasReadGroups(void) const
+    \brief Returns \c true if header contains any \@RG entries
+*/
 bool SamHeader::HasReadGroups(void) const {
     return (!ReadGroups.IsEmpty());
 }
 
-// query if header contains @PG ID:<ProgramName>
+/*! \fn bool SamHeader::HasProgramName(void) const
+    \brief Returns \c true if header contains \@PG ID:\<ProgramName\>
+*/
 bool SamHeader::HasProgramName(void) const {
     return (!ProgramName.empty());
 }
 
-// query if header contains @HD VN:<ProgramVersion>
+/*! \fn bool SamHeader::HasProgramVersion(void) const
+    \brief Returns \c true if header contains \@PG VN:\<ProgramVersion\>
+*/
 bool SamHeader::HasProgramVersion(void) const {
     return (!ProgramVersion.empty());
 }
 
-// query if header contains @HD CL:<ProgramCommandLine>
+/*! \fn bool SamHeader::HasProgramCommandLine(void) const
+    \brief Returns \c true if header contains \@PG CL:\<ProgramCommandLine\>
+*/
 bool SamHeader::HasProgramCommandLine(void) const {
     return (!ProgramCommandLine.empty());
 }
 
-// query if header contains @CO entries
+/*! \fn bool SamHeader::HasComments(void) const
+    \brief Returns \c true if header contains any \@CO entries
+*/
 bool SamHeader::HasComments(void) const {
     return (!Comments.empty());
 }
 
-// validation
+/*! \fn bool SamHeader::IsValid(bool verbose = false) const
+    \brief Checks header contents for required data and proper formatting.
+    \param verbose If set to true, validation errors & warnings will be printed to stderr.
+                   Otherwise, output is suppressed and only validation check occurs.
+    \return \c true if SAM header is well-formed
+*/
 bool SamHeader::IsValid(bool verbose) const {
     SamHeaderValidator validator(*this);
     return validator.Validate(verbose);
 }
+
+/*! \fn void SamHeader::SetHeaderText(const std::string& headerText)
+    \brief Replaces header contents with \a headerText.
+    \param headerText SAM formatted-text that will be parsed into data fields
+*/
+void SamHeader::SetHeaderText(const std::string& headerText) {
+
+    // clear prior data
+    Clear();
+
+    // parse header text into data
+    SamFormatParser parser(*this);
+    parser.Parse(headerText);
+}
+
+/*! \fn std::string SamHeader::ToString(void) const
+    \brief Converts data fields to SAM-formatted text.
+
+    Applies any local modifications made since creating this object or calling SetHeaderText().
+
+    \return SAM-formatted header text
+*/
+string SamHeader::ToString(void) const {
+    SamFormatPrinter printer(*this);
+    return printer.ToString();
+}