Merge pull request #108 from eseiler/doc/groups

[DOC] Add groups

include/hibf/all.hpp

@@ -7,15 +7,36 @@
 
 /*!\file
  * \author Enrico Seiler <enrico.seiler AT fu-berlin.de>
- * \brief Meta-header for the \link search_dream_index Search / DREAM Index submodule \endlink.
+ * \brief Meta-header.
  */
 
-/*!\defgroup search_dream_index DREAM Index
- * \brief Provides seqan::hibf::interleaved_bloom_filter.
- * \ingroup search
- * \see search
+/*!\defgroup ibf IBF
+ * \brief The Interleaved Bloom Filter.
  */
 
+/*!\defgroup hibf HIBF
+ * \brief The Hierarchical Interleaved Bloom Filter.
+ */
+
+/*!\defgroup hibf_sketch Sketching
+ * \brief Sketching.
+ * \ingroup hibf
+ */
+
+/*!\defgroup hibf_sketch_toolbox Toolbox
+ * \brief Sketching toolbox.
+ * \ingroup hibf_sketch
+ */
+
+/*!\defgroup hibf_layout Layout
+ * \brief The Layout.
+ * \ingroup hibf
+ */
+
+/*!\defgroup hibf_build Build
+ * \brief Building.
+ * \ingroup hibf
+ */
 #pragma once
 
 #include <hibf/interleaved_bloom_filter.hpp>

include/hibf/build/bin_size_in_bits.hpp

@@ -20,13 +20,20 @@
 namespace seqan::hibf::build
 {
 
+/*!\brief Contains parameters for bin_size_in_bits.
+ * \ingroup hibf_build
+ * \qualifier strong
+ */
 struct bin_size_parameters
 {
     double fpr{};
     size_t hash_count{};
     size_t elements{};
 };
 
+/*!\brief Computes the bin size.
+ * \ingroup hibf_build
+ */
 inline size_t bin_size_in_bits(bin_size_parameters const & params)
 {
     double const numerator{-static_cast<double>(params.elements * params.hash_count)};

include/hibf/build/build_data.hpp

@@ -18,6 +18,9 @@
 namespace seqan::hibf::build
 {
 
+/*!\brief Contains information used for building.
+ * \ingroup hibf_build
+ */
 struct build_data
 {
     std::atomic<size_t> ibf_number{};

include/hibf/build/compute_kmers.hpp

@@ -21,6 +21,9 @@
 namespace seqan::hibf::build
 {
 
+/*!\brief Computes kmers.
+ * \ingroup hibf_build
+ */
 void compute_kmers(robin_hood::unordered_flat_set<uint64_t> & kmers,
                    build_data const & data,
                    layout::layout::user_bin const & record);

include/hibf/build/construct_ibf.hpp

@@ -18,6 +18,9 @@
 namespace seqan::hibf::build
 {
 
+/*!\brief Constructs an IBF of the HIBF.
+ * \ingroup hibf_build
+ */
 seqan::hibf::interleaved_bloom_filter construct_ibf(robin_hood::unordered_flat_set<uint64_t> & parent_kmers,
                                                     robin_hood::unordered_flat_set<uint64_t> & kmers,
                                                     size_t const number_of_bins,

include/hibf/build/insert_into_ibf.hpp

@@ -19,13 +19,18 @@
 namespace seqan::hibf::build
 {
 
-// automatically does naive splitting if number_of_bins > 1
+/*!\brief Inserts values into an IBF.
+ * \ingroup hibf_build
+ * \details
+ * Automatically does naive splitting if number_of_bins > 1.
+ */
 void insert_into_ibf(robin_hood::unordered_flat_set<uint64_t> const & kmers,
                      size_t const number_of_bins,
                      size_t const bin_index,
                      seqan::hibf::interleaved_bloom_filter & ibf,
                      timer<concurrent::yes> & fill_ibf_timer);
 
+//!\overload
 void insert_into_ibf(build_data const & data,
                      layout::layout::user_bin const & record,
                      seqan::hibf::interleaved_bloom_filter & ibf);

include/hibf/build/update_parent_kmers.hpp

@@ -20,6 +20,9 @@
 namespace seqan::hibf::build
 {
 
+/*!\brief Updates stored values of the parent IBF.
+ * \ingroup hibf_build
+ */
 inline void update_parent_kmers(robin_hood::unordered_flat_set<uint64_t> & parent_kmers,
                                 robin_hood::unordered_flat_set<uint64_t> const & kmers,
                                 timer<concurrent::yes> & merge_kmers_timer)

include/hibf/build/update_user_bins.hpp

@@ -16,6 +16,9 @@
 namespace seqan::hibf::build
 {
 
+/*!\brief Updates user bins stored in HIBF.
+ * \ingroup hibf_build
+ */
 inline void update_user_bins(std::vector<int64_t> & filename_indices, layout::layout::user_bin const & record)
 {
     std::fill_n(filename_indices.begin() + record.storage_TB_id, record.number_of_technical_bins, record.idx);

include/hibf/config.hpp

@@ -26,6 +26,7 @@ namespace seqan::hibf
 using insert_iterator = std::insert_iterator<robin_hood::unordered_flat_set<uint64_t>>;
 
 /*!\brief The configuration used to build an (H)IBF
+ * \ingroup hibf
  *
  * # The (H)IBF config
  *

include/hibf/detail/timer.hpp

@@ -22,12 +22,18 @@
 namespace seqan::hibf
 {
 
+/*!\brief Whether the timer is concurrent.
+ * \ingroup hibf_build
+ */
 enum class concurrent
 {
-    no,
-    yes
+    no, //!< Not concurrent.
+    yes //!< Concurrent.
 };
 
+/*!\brief Timer.
+ * \ingroup hibf_build
+ */
 template <concurrent concurrency>
 class timer
 {
@@ -104,8 +110,13 @@ class timer
     rep_t ticks{};
 };
 
-// seqan::hibf::{serial,concurrent}_timer is easier to use than `seqan::hibf::timer<seqan::hibf::concurrent::{no,yes}.
+/*!\brief Alias for timer<concurrent::no>
+ * \ingroup hibf_build
+ */
 using serial_timer = timer<concurrent::no>;
+/*!\brief Alias for timer<concurrent::yes>
+ * \ingroup hibf_build
+ */
 using concurrent_timer = timer<concurrent::yes>;
 
 } // namespace seqan::hibf

include/hibf/hierarchical_interleaved_bloom_filter.hpp

@@ -29,6 +29,7 @@ namespace seqan::hibf
 {
 
 /*!\brief The Hierarchical Interleaved Bloom Filter (HIBF) - Fast answers to set-membership queries for multiple bins.
+ * \ingroup hibf
  * \details
  *
  * This class improves the [seqan::hibf::interleaved_bloom_filter][1] by adding additional bookkeeping that allows

include/hibf/interleaved_bloom_filter.hpp

@@ -35,36 +35,44 @@
 
 namespace seqan::hibf
 {
-//!\brief A strong type that represents the number of bins for the seqan::hibf::interleaved_bloom_filter.
-//!\ingroup search_dream_index
+/*!\brief A strong type that represents the number of bins for the seqan::hibf::interleaved_bloom_filter.
+ * \ingroup ibf
+ * \qualifier strong
+ */
 struct bin_count
 {
     size_t value;
 };
 
-//!\brief A strong type that represents the number of bits for each bin in the seqan::hibf::interleaved_bloom_filter.
-//!\ingroup search_dream_index
+/*!\brief A strong type that represents the number of bits for each bin in the seqan::hibf::interleaved_bloom_filter.
+ * \ingroup ibf
+ * \qualifier strong
+ */
 struct bin_size
 {
     size_t value;
 };
 
-//!\brief A strong type that represents the number of hash functions for the seqan::hibf::interleaved_bloom_filter.
-//!\ingroup search_dream_index
+/*!\brief A strong type that represents the number of hash functions for the seqan::hibf::interleaved_bloom_filter.
+ * \ingroup ibf
+ * \qualifier strong
+ */
 struct hash_function_count
 {
     size_t value;
 };
 
-//!\brief A strong type that represents the bin index for the seqan::hibf::interleaved_bloom_filter.
-//!\ingroup search_dream_index
+/*!\brief A strong type that represents the bin index for the seqan::hibf::interleaved_bloom_filter.
+ * \ingroup ibf
+ * \qualifier strong
+ */
 struct bin_index
 {
     size_t value;
 };
 
 /*!\brief The IBF binning directory. A data structure that efficiently answers set-membership queries for multiple bins.
- * \ingroup search_dream_index
+ * \ingroup ibf
  * \tparam data_layout_mode_ Indicates whether the underlying data type is compressed. See seqan::hibf::data_layout.
  * \implements seqan::hibf::cerealisable
  *
@@ -217,6 +225,7 @@ class interleaved_bloom_filter
                              seqan::hibf::bin_size size,
                              seqan::hibf::hash_function_count funs = seqan::hibf::hash_function_count{2u});
 
+    //!\brief Construct from seqan::hibf::config.
     interleaved_bloom_filter(config & configuration);
     //!\}
 
@@ -814,7 +823,7 @@ inline interleaved_bloom_filter::membership_agent_type interleaved_bloom_filter:
 
 /*!\brief A data structure that behaves like a std::vector and can be used to consolidate the results of multiple calls
  *        to seqan::hibf::interleaved_bloom_filter::membership_agent_type::bulk_contains.
- * \ingroup search_dream_index
+ * \ingroup ibf
  * \tparam value_t The type of the count. Must model std::integral.
  *
  * \details

include/hibf/layout/compute_fpr_correction.hpp

@@ -8,6 +8,10 @@
 namespace seqan::hibf::layout
 {
 
+/*!\brief Contains parameters for compute_fpr_correction.
+ * \ingroup hibf_layout
+ * \qualifier strong
+ */
 struct fpr_correction_parameters
 {
     double fpr{};
@@ -16,6 +20,7 @@ struct fpr_correction_parameters
 };
 
 /*!\brief Precompute f_h factors that adjust the split bin size to prevent FPR inflation due to multiple testing.
+ * \ingroup hibf_layout
  * \sa https://godbolt.org/z/zTj1v9W94
  */
 std::vector<double> compute_fpr_correction(fpr_correction_parameters const & params);

include/hibf/layout/compute_layout.hpp

@@ -11,6 +11,7 @@ namespace seqan::hibf::layout
 {
 
 /*!\brief Computes the layout and stores the kmer_counts and sketches in the respective vectors for further use.
+ * \ingroup hibf_layout
  * \param config The configuration to compute the layout with.
  * \param[in,out] kmer_counts The vector that will store the kmer counts (estimations).
  * \param[in,out] sketches The vector that will store the sketches.
@@ -19,6 +20,7 @@ namespace seqan::hibf::layout
 layout
 compute_layout(config const & config, std::vector<size_t> & kmer_counts, std::vector<sketch::hyperloglog> & sketches);
 
+//!\overload
 layout compute_layout(config const & config);
 
 } // namespace seqan::hibf::layout

include/hibf/layout/data_store.hpp

@@ -14,10 +14,13 @@
 namespace seqan::hibf::layout
 {
 
+/*!\brief Contains information used for the layout.
+ * \ingroup hibf_layout
+ */
 struct data_store
 {
     /*!\brief Stores information of the previous level of a given IBF.
-     *
+     * \details
      * When computing a hierarchical layout, the `data_store` data structure is used with local copies for each IBF
      * within the hierarchical structure of the HIBF. To keep track of the hierarchy, the `previous_level` stores
      * information about the previous level (where the corresponding merged bin is located).
@@ -51,7 +54,7 @@ struct data_store
     //!\}
 
     /*!\name Local Storage one IBF in the HIBF.
-     *
+     * \details
      * These member variables change on each IBF of the HIBF s.t. the current IBF can be constructed from
      * the current subset of data. The same data is also used for the top level IBF that holds all the data.
      * \{

include/hibf/layout/graph.hpp

@@ -22,7 +22,9 @@
 namespace seqan::hibf::layout
 {
 
-// Currently, the layout is structured by user bin.
+/*!\brief Contains the layout graph structure.
+ * \ingroup hibf_layout
+ */
 struct graph
 {
 

include/hibf/layout/hierarchical_binning.hpp

@@ -13,6 +13,9 @@
 namespace seqan::hibf::layout
 {
 
+/*!\brief Hierarchical binning algorithm.
+ * \ingroup hibf_layout
+ */
 class hierarchical_binning
 {
 private:

include/hibf/layout/layout.hpp

@@ -12,7 +12,9 @@
 namespace seqan::hibf::layout
 {
 
-// Currently, the layout is structured by user bin.
+/*!\brief The layout.
+ * \ingroup hibf_layout
+ */
 struct layout
 {
     struct max_bin