-// retrieves the SamReadGroup object associated with this ID
-// if readGroupId is unknown, a new SamReadGroup is created with this ID
-// and a reference to this new read group entry is returned (like std::map)
+/*! \fn SamReadGroup& SamReadGroupDictionary::operator[](const std::string& readGroupId)
+ \brief Retrieves the modifiable SamReadGroup that matches \a readGroupId.
+
+ NOTE - If the dictionary contains no read group matching this ID, this function inserts
+ a new one with this ID, and returns a reference to it.
+
+ If you want to avoid this insertion behavior, check the result of Contains() before
+ using this operator.
+
+ \param readGroupId ID of read group to retrieve
+ \return a modifiable reference to the SamReadGroup associated with the ID
+*/