Updated Doxygen comments

[bamtools.git] / src / api / SamSequenceDictionary.cpp

diff --git a/src/api/SamSequenceDictionary.cpp b/src/api/SamSequenceDictionary.cpp
index 34cf3284dbbca650e3597de8eb41c2d3f853090c..61eae2529fb8ea6a02d7f01e1e32f492f3d5d3ee 100644 (file)
--- a/src/api/SamSequenceDictionary.cpp
+++ b/src/api/SamSequenceDictionary.cpp
@@ -2,7 +2,7 @@
 // SamSequenceDictionary.cpp (c) 2010 Derek Barnett
 // Marth Lab, Department of Biology, Boston College
 // ---------------------------------------------------------------------------
-// Last modified: 1 October 2011 (DB)
+// Last modified: 10 October 2011 (DB)
 // ---------------------------------------------------------------------------
 // Provides methods for operating on a collection of SamSequence entries.
 // *************************************************************************
@@ -37,33 +37,38 @@ SamSequenceDictionary::SamSequenceDictionary(const SamSequenceDictionary& other)
 SamSequenceDictionary::~SamSequenceDictionary(void) { }
 
 /*! \fn void SamSequenceDictionary::Add(const SamSequence& sequence)
-    \brief Adds a sequence to the dictionary.
+    \brief Appends a sequence to the dictionary.
 
     Duplicate entries are silently discarded.
 
-    \param sequence entry to be added
+    \param[in] sequence entry to be added
 */
 void SamSequenceDictionary::Add(const SamSequence& sequence) {
-
-    // TODO: report error on attempted duplicate?
-
     if ( IsEmpty() || !Contains(sequence) )
         m_data.push_back(sequence);
 }
 
 /*! \fn void SamSequenceDictionary::Add(const std::string& name, const int& length)
-    \brief Adds a sequence to the dictionary.
+    \brief Appends a sequence to the dictionary.
 
     This is an overloaded function.
 
-    \param name name of sequence entry to be added
-    \param length length of sequence entry to be added
+    \param[in] name name of sequence entry to be added
+    \param[in] length length of sequence entry to be added
     \sa Add()
 */
 void SamSequenceDictionary::Add(const std::string& name, const int& length) {
     Add( SamSequence(name, length) );
 }
 
+/*! \fn void SamSequenceDictionary::Add(const SamSequenceDictionary& sequences)
+    \brief Appends another sequence dictionary to this one
+
+    This is an overloaded function.
+
+    \param[in] sequences sequence dictionary to be appended
+    \sa Add()
+*/
 void SamSequenceDictionary::Add(const SamSequenceDictionary& sequences) {
     SamSequenceConstIterator seqIter = sequences.ConstBegin();
     SamSequenceConstIterator seqEnd  = sequences.ConstEnd();
@@ -72,11 +77,11 @@ void SamSequenceDictionary::Add(const SamSequenceDictionary& sequences) {
 }
 
 /*! \fn void SamSequenceDictionary::Add(const std::vector<SamSequence>& sequences)
-    \brief Adds multiple sequences to the dictionary.
+    \brief Appends multiple sequences to the dictionary.
 
     This is an overloaded function.
 
-    \param sequences entries to be added
+    \param[in] sequences entries to be added
     \sa Add()
 */
 void SamSequenceDictionary::Add(const std::vector<SamSequence>& sequences) {
@@ -87,11 +92,11 @@ void SamSequenceDictionary::Add(const std::vector<SamSequence>& sequences) {
 }
 
 /*! \fn void SamSequenceDictionary::Add(const std::map<std::string, int>& sequenceMap)
-    \brief Adds multiple sequences to the dictionary.
+    \brief Appends multiple sequences to the dictionary.
 
     This is an overloaded function.
 
-    \param sequenceMap map of sequence entries (name => length) to be added
+    \param[in] sequenceMap map of sequence entries (name => length) to be added
     \sa Add()
 */
 void SamSequenceDictionary::Add(const std::map<std::string, int>& sequenceMap) {
@@ -148,7 +153,8 @@ SamSequenceConstIterator SamSequenceDictionary::ConstEnd(void) const {
 
 /*! \fn bool SamSequenceDictionary::Contains(const std::string& sequenceName) const
     \brief Returns true if dictionary contains sequence.
-    \param sequenceName search for sequence matching this name
+
+    \param[in] sequenceName search for sequence matching this name
     \return \c true if dictionary contains a sequence with this name
 */
 bool SamSequenceDictionary::Contains(const std::string& sequenceName) const {
@@ -160,7 +166,7 @@ bool SamSequenceDictionary::Contains(const std::string& sequenceName) const {
 
     This is an overloaded function.
 
-    \param sequence search for this sequence
+    \param[in] sequence search for this sequence
     \return \c true if dictionary contains sequence (matching on name)
 */
 bool SamSequenceDictionary::Contains(const SamSequence& sequence) const {
@@ -215,7 +221,7 @@ bool SamSequenceDictionary::IsEmpty(void) const {
 
     This is an overloaded function.
 
-    \param sequence SamSequence to remove (matching on name)
+    \param[in] sequence SamSequence to remove (matching on name)
 */
 void SamSequenceDictionary::Remove(const SamSequence& sequence) {
     Remove( sequence.Name );
@@ -224,7 +230,7 @@ void SamSequenceDictionary::Remove(const SamSequence& sequence) {
 /*! \fn void SamSequenceDictionary::Remove(const std::string& sequenceName)
     \brief Removes sequence from dictionary, if found.
 
-    \param sequenceName name of sequence to remove
+    \param[in] sequenceName name of sequence to remove
     \sa Remove()
 */
 void SamSequenceDictionary::Remove(const std::string& sequenceName) {
@@ -237,7 +243,7 @@ void SamSequenceDictionary::Remove(const std::string& sequenceName) {
 
     This is an overloaded function.
 
-    \param sequences sequences to remove
+    \param[in] sequences sequences to remove
     \sa Remove()
 */
 void SamSequenceDictionary::Remove(const std::vector<SamSequence>& sequences) {
@@ -252,7 +258,7 @@ void SamSequenceDictionary::Remove(const std::vector<SamSequence>& sequences) {
 
     This is an overloaded function.
 
-    \param sequenceNames names of the sequences to remove
+    \param[in] sequenceNames names of the sequences to remove
     \sa Remove()
 */
 void SamSequenceDictionary::Remove(const std::vector<std::string>& sequenceNames) {
@@ -273,13 +279,11 @@ int SamSequenceDictionary::Size(void) const {
 /*! \fn SamSequence& SamSequenceDictionary::operator[](const std::string& sequenceName)
     \brief Retrieves the modifiable SamSequence that matches \a sequenceName.
 
-    NOTE - If the dictionary contains no sequence matching this name, this function inserts
-    a new one with this name (length:0), and returns a reference to it.
-
-    If you want to avoid this insertion behavior, check the result of Contains() before
-    using this operator.
+    \note If the dictionary contains no sequence matching this name, this function inserts
+    a new one with this name (length:0), and returns a reference to it. If you want to avoid
+    this insertion behavior, check the result of Contains() before using this operator.
 
-    \param sequenceName name of sequence to retrieve
+    \param[in] sequenceName name of sequence to retrieve
     \return a modifiable reference to the SamSequence associated with the name
 */
 SamSequence& SamSequenceDictionary::operator[](const std::string& sequenceName) {