Merge pull request #50 from Illumina/ipa-4146-update-documentation

IPA-4146: Update documentation

docs/Doxyfile.in

@@ -806,7 +806,7 @@ RECURSIVE              = YES
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                = ../../src/ext/csharp ../../src/tests
+EXCLUDE                =
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded
@@ -822,7 +822,7 @@ EXCLUDE_SYMLINKS       = NO
 # Note that the wildcards are matched against the file with absolute path, so to
 # exclude all test directories for example use the pattern */test/*
 
-EXCLUDE_PATTERNS       = @PROJECT_SOURCE_DIR@/src/ext/csharp/src/*
+EXCLUDE_PATTERNS       = @PROJECT_SOURCE_DIR@/src/ext/csharp/src/* @PROJECT_SOURCE_DIR@/Build
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 # (namespaces, classes, functions, etc.) that should be excluded from the

docs/src/changes.md

@@ -10,7 +10,7 @@
 Commit  | Description
 ------- | -----------
         | Update documentation
-        | Added summary tests
+0b22102 | Added summary tests
 13f1fb4 | Added summary logic
 339a914 | Added summary model
 aca0152 | Added run metrics

interop/io/metric_file_stream.h

@@ -65,7 +65,8 @@ std::string write_interop_to_buffer(const MetricSet& metrics)
  * @throw incomplete_file_exception
  */
 template<class MetricSet>
-void read_interop_from_buffer(::uint8_t* buffer, size_t buffer_size, MetricSet& metrics) _INTEROP_FORMAT_THROWS
+void read_interop_from_buffer(::uint8_t* buffer, size_t buffer_size, MetricSet& metrics)  throw
+(interop::io::file_not_found_exception, interop::io::bad_format_exception, interop::io::incomplete_file_exception)
 {
     detail::membuf sbuf(reinterpret_cast<char*>(buffer), reinterpret_cast<char*>(buffer) + buffer_size);
     std::istream in(&sbuf);
@@ -83,7 +84,8 @@ void read_interop_from_buffer(::uint8_t* buffer, size_t buffer_size, MetricSet&
  * @throw incomplete_file_exception
  */
 template<class MetricSet>
-void read_interop(const std::string& runDirectory, MetricSet& metrics, const bool useOut=true) _INTEROP_FORMAT_THROWS
+void read_interop(const std::string& runDirectory, MetricSet& metrics, const bool useOut=true)   throw
+(interop::io::file_not_found_exception, interop::io::bad_format_exception, interop::io::incomplete_file_exception)
 {
     std::string fileName = detail::interop_filename(runDirectory, metrics.name(), useOut);
     std::ifstream fin(fileName.c_str(), std::ios::binary);

interop/io/stream_exceptions.h

@@ -12,18 +12,19 @@
 #pragma once
 #include <string>
 #include <stdexcept>
+#include "interop/util/exception_specification.h"
 
 #ifdef _MSC_VER
 #pragma warning(disable:4290) // MSVC warns that it ignores the exception specification.
 #endif
 
-#define _INTEROP_FORMAT_THROWS throw(   interop::io::file_not_found_exception, \
-                                        interop::io::bad_format_exception, \
-                                        interop::io::incomplete_file_exception)
-
 namespace illumina {
     namespace interop {
         namespace io {
+            /** @defgroup interop_exceptions Exceptions
+             *
+             * List of exceptions thrown by the InterOp library
+             */
             /** Base exception for all format errors
              */
             struct format_exception : public std::runtime_error {
@@ -37,6 +38,7 @@ namespace illumina {
              *
              * Exceptions that will be thrown if a problem occurs while reading a binary InterOp file.
              *
+             * @ingroup interop_exceptions
              * @{
              */
             /** Exception raised if the InterOp file is not found in the file system

interop/logic/metric/q_metric.h

@@ -40,7 +40,7 @@ namespace illumina { namespace interop { namespace logic { namespace metric {
      *
      * @param metrics q-metric set
      */
-    inline void populate_cumulative_distribution(model::metric_base::metric_set<model::metrics::q_metric>& metrics) _INTEROP_MODEL_THROWS
+    inline void populate_cumulative_distribution(model::metric_base::metric_set<model::metrics::q_metric>& metrics) throw( model::index_out_of_bounds_exception )
     {
         if(metrics.size()==0) return;
         typedef model::metrics::q_metric q_metric;

interop/logic/summary/error_summary.h

@@ -84,7 +84,7 @@ void cache_error_by_lane_read(I beg,
                               I end,
                               const size_t max_cycle,
                               const std::vector<read_cycle>& cycle_to_read,
-                              summary_by_lane_read<float>& summary_by_lane_read) _INTEROP_MODEL_THROWS
+                              summary_by_lane_read<float>& summary_by_lane_read) throw( model::index_out_of_bounds_exception )
 {
     typedef std::pair<size_t, size_t> key_t;
     typedef std::pair<float, float> value_t;
@@ -166,7 +166,7 @@ void cache_cycle_state_by_lane_read(I beg, I end,
         const read_cycle& read = cycle_to_read[beg->cycle()-1];
         if(read.number == 0) continue;
         INTEROP_ASSERT((read.number-1) < tmp.size());
-        size_t id = static_cast<size_t>(model::metric_base::base_metric::id(beg->lane(), beg->tile()));
+        const size_t id = static_cast<size_t>(model::metric_base::base_metric::id(beg->lane(), beg->tile()));
         tmp[read.number-1][id].update(beg->cycle());
     }
     for(size_t read=0;read<tmp.size();++read)
@@ -200,7 +200,7 @@ void cache_cycle_state_by_lane_read(I beg, I end,
  * @param run destination run summary
  */
 template<typename I>
-void summarize_error_metrics(I beg, I end, model::summary::run_summary &run) _INTEROP_MODEL_THROWS
+void summarize_error_metrics(I beg, I end, model::summary::run_summary &run) throw( model::index_out_of_bounds_exception )
 {
     typedef summary_by_lane_read<float> summary_by_lane_read_t;
     typedef std::vector<std::vector< model::run::cycle_range> > cycle_range_read_lane_t;

interop/logic/summary/extraction_summary.h

@@ -61,7 +61,7 @@ namespace summary
      * @param run destination run summary
      */
     template<typename I>
-    void summarize_extraction_metrics(I beg, I end, const size_t channel, model::summary::run_summary &run) _INTEROP_MODEL_THROWS
+    void summarize_extraction_metrics(I beg, I end, const size_t channel, model::summary::run_summary &run) throw( model::index_out_of_bounds_exception )
     {
         typedef typename model::metrics::extraction_metric::ushort_t ushort_t;
         typedef summary_by_lane_read<ushort_t> summary_by_lane_read_t;

interop/logic/summary/quality_summary.h

@@ -101,7 +101,7 @@ namespace summary
      * @param run destination run summary
      */
     template<typename I>
-    void summarize_quality_metrics(I beg, I end, const size_t qval_index, model::summary::run_summary &run) _INTEROP_MODEL_THROWS
+    void summarize_quality_metrics(I beg, I end, const size_t qval_index, model::summary::run_summary &run) throw( model::index_out_of_bounds_exception )
     {
         typedef model::metrics::q_metric::uint_t uint_t;
         typedef model::summary::lane_summary lane_summary;

interop/logic/summary/run_summary.h

@@ -52,7 +52,7 @@ namespace summary
      * @param metrics source collection of all metrics
      * @param summary destination run summary
      */
-    inline void summarize_run_metrics(const model::metrics::run_metrics& metrics, model::summary::run_summary& summary) _INTEROP_MODEL_THROWS
+    inline void summarize_run_metrics(const model::metrics::run_metrics& metrics, model::summary::run_summary& summary) throw( model::index_out_of_bounds_exception )
     {
         using namespace model::metrics;
         if(metrics.empty()) return;

interop/logic/summary/tile_summary.h

@@ -41,7 +41,7 @@ namespace summary
     * @param run destination run summary
     */
     template<typename I>
-    void summarize_tile_metrics(I beg, I end, model::summary::run_summary &run) _INTEROP_MODEL_THROWS
+    void summarize_tile_metrics(I beg, I end, model::summary::run_summary &run) throw( model::index_out_of_bounds_exception )
     {
         typedef typename model::metrics::tile_metric::read_metric_vector read_metric_vector_t;
         typedef typename read_metric_vector_t::const_iterator const_read_metric_iterator;

interop/logic/utils/channel.h

@@ -74,7 +74,7 @@ namespace illumina { namespace interop { namespace logic { namespace utils
      * @return string vector of expected channels
      */
     template<class I>
-    std::vector<std::string> expected_order(I beg, I end) _INTEROP_CHANNEL_THROWS
+    std::vector<std::string> expected_order(I beg, I end) throw( model::invalid_channel_exception )
     {
         std::vector<std::string> expected;
         expected.reserve(std::distance(beg, end));

interop/model/metric_base/metric_set.h

@@ -163,7 +163,7 @@ namespace illumina {
                      * @param cycle cycle
                      * @return metric
                      */
-                    const metric_type& get_metric(uint_t lane, uint_t tile, uint_t cycle=0) const _INTEROP_MODEL_THROWS
+                    const metric_type& get_metric(uint_t lane, uint_t tile, uint_t cycle=0) const throw( model::index_out_of_bounds_exception )
                     {
                         try {
                             return get_metric(metric_type::id(lane, tile, cycle));
@@ -184,7 +184,7 @@ namespace illumina {
                      * @param key unique id built from lane, tile and cycle (if available)
                      * @return metric
                      */
-                    const metric_type& get_metric(id_t key) const _INTEROP_MODEL_THROWS
+                    const metric_type& get_metric(id_t key) const throw( model::index_out_of_bounds_exception )
                     {
                         typename std::map<id_t, size_t>::const_iterator it = m_id_map.find(key);
                         if(it == m_id_map.end())
@@ -342,7 +342,7 @@ namespace illumina {
                      * @param cycle cycle
                      * @return metric
                      */
-                    metric_type& get_metric_ref(uint_t lane, uint_t tile, uint_t cycle=0) _INTEROP_MODEL_THROWS
+                    metric_type& get_metric_ref(uint_t lane, uint_t tile, uint_t cycle=0) throw( model::index_out_of_bounds_exception )
                     {
                         try{
                             return get_metric_ref(metric_type::id(lane, tile, cycle));
@@ -363,7 +363,7 @@ namespace illumina {
                      * @param key unique id built from lane, tile and cycle (if available)
                      * @return metric
                      */
-                    metric_type& get_metric_ref(id_t key) _INTEROP_MODEL_THROWS
+                    metric_type& get_metric_ref(id_t key) throw( model::index_out_of_bounds_exception )
                     {
                         typename std::map<id_t, size_t>::const_iterator it = m_id_map.find(key);
                         if(it == m_id_map.end())

interop/model/metrics/corrected_intensity_metric.h

@@ -199,6 +199,7 @@ namespace illumina {
                      *
                      * Per tile per cycle per channel average intensity values
                      *
+                     * @ingroup run_metrics
                      * @ref illumina::interop::model::metrics::corrected_intensity_metric "See full class description"
                      * @{
                      */

interop/model/metrics/error_metric.h

@@ -79,6 +79,7 @@ namespace illumina {
                      *
                      * @ref illumina::interop::model::metrics::error_metric "See full class description"
                      *
+                     * @ingroup run_metrics
                      * @{
                      */
                     /** Calculated error rate, as determined by a spiked in PhiX control sample.

interop/model/metrics/extraction_metric.h

@@ -183,6 +183,7 @@ namespace illumina {
                      *
                      * @ref illumina::interop::model::metrics::extraction_metric "See full class description"
                      *
+                     * @ingroup run_metrics
                      * @note All metrics in this class are supported by all versions
                      * @{
                      */

interop/model/metrics/image_metric.h

@@ -146,6 +146,7 @@ namespace illumina {
                      *
                      * @ref illumina::interop::model::metrics::image_metric "See full class description"
                      *
+                     * @ingroup run_metrics
                      * @note All metrics in this class are supported by all versions
                      * @{
                      */

interop/model/metrics/index_metric.h

@@ -73,6 +73,7 @@ class index_info
      *
      *
      * @ref illumina::interop::model::metrics::index_info "See full class description"
+     * @ingroup index_metric
      * @{
      */
     /** Get the index sequence
@@ -149,6 +150,7 @@ class index_metric : public metric_base::base_read_metric
      *
      *
      * @ref illumina::interop::model::metrics::index_metric "See full class description"
+     * @ingroup run_metrics
      * @{
      */
     /** Get the number of indexes

interop/model/metrics/q_metric.h

@@ -42,6 +42,14 @@ namespace illumina {
                                                                                         m_upper(upper),
                                                                                         m_value(value){}
                 public:
+                    /** @defgroup q_score_bin Quality Bin
+                     *
+                     * Bin information for a q-score
+                     *
+                     * @ref illumina::interop::model::metrics::q_score_bin "See full class description"
+                     * @ingroup q_score_header
+                     * @{
+                     */
                     /** Lower end of the bin
                      *
                      * @return lower end of the bin
@@ -57,6 +65,7 @@ namespace illumina {
                      * @return value of the bin
                      */
                     bin_type value()const{return m_value;}
+                    /** @} */
 
                 private:
                     bin_type m_lower;
@@ -88,6 +97,15 @@ namespace illumina {
                      */
                     q_score_header(const qscore_bin_vector_type& bins) :
                             m_qscoreBins(bins), m_bin_count(bins.size()){}
+
+                    /** @defgroup q_score_header Quality Metric Header
+                     *
+                     * Collection of q-score bins
+                     *
+                     * @ref illumina::interop::model::metrics::q_score_header "See full class description"
+                     * @ingroup q_metric
+                     * @{
+                     */
                     /** Get a q-score bin
                      *
                      * @return q-score bin
@@ -140,6 +158,7 @@ namespace illumina {
                         while(index < m_qscoreBins.size() && binAt(index).value() < qval) index++;
                         return index+1;
                     }
+                    /** @} */
                     /** Generate a default header
                      *
                      * @return default header
@@ -234,6 +253,7 @@ namespace illumina {
                      * @ref illumina::interop::model::metrics::q_metric "See full class description"
                      *
                      * @note All metrics in this class are supported by all versions
+                     * @ingroup run_metrics
                      * @{
                      */
                     /** Q-score value of the histogram

interop/model/metrics/tile_metric.h

@@ -56,7 +56,7 @@ namespace illumina {
                      * Per tile per read metrics
                      *
                      * @ref illumina::interop::model::metrics::tile_metric "See full class description"
-                     *
+                     * @ingroup tile_metric
                      * @ref tile_metric "See read metrics"
                      * @{
                      */
@@ -204,6 +204,7 @@ namespace illumina {
                      *
                      * @ref read_metric "See read metrics"
                      *
+                     * @ingroup run_metrics
                      * @note All metrics in this class are supported by all versions
                      * @{
                      */

interop/model/model_exceptions.h

@@ -7,19 +7,23 @@
  */
 #pragma once
 #include <stdexcept>
+#include "interop/util/exception_specification.h"
 
 #ifdef _MSC_VER
 #pragma warning(disable:4290) // MSVC warns that it ignores the exception specification.
 #endif
 
-
-#define _INTEROP_MODEL_THROWS throw( interop::model::index_out_of_bounds_exception )
-#define _INTEROP_CHANNEL_THROWS throw( interop::model::invalid_channel_exception )
-
 namespace illumina {
 namespace interop {
 namespace model {
 
+    /** @defgroup model_exceptions Model Exceptions
+     *
+     * Exceptions that can be thrown if a problem occurs while using the model
+     *
+     * @ingroup interop_exceptions
+     * @{
+     */
     /** Exception raised if an index goes out of bounds
      */
     struct index_out_of_bounds_exception : public std::out_of_range {
@@ -40,6 +44,7 @@ namespace model {
         invalid_channel_exception(const std::string &mesg) : std::runtime_error(mesg) { }
     };
 
+    /** @} */
 }
 }
 }

interop/model/run/cycle_range.h

@@ -20,6 +20,7 @@ namespace run
 {
 
     /** Defines a range over cycles
+     *
      */
     class cycle_range
     {
@@ -39,6 +40,14 @@ namespace run
         }
 
     public:
+        /** @defgroup cycle_range Cycle range
+         *
+         * Information describing the cycle rnage
+         *
+         * @ingroup read_info
+         * @ref illumina::interop::model::run::cycle_range "See full class description"
+         * @{
+         */
         /** Get the index of the first cycle
          *
          * @return index of first cycle
@@ -72,6 +81,7 @@ namespace run
         {
             m_last_cycle = val;
         }
+        /** @} */
 
     public:
         /** Update the cycle state