Merge pull request #3060 from eseiler/doc/doxygen

[DOC] doxygen 1.9.5/1.9.6

CHANGELOG.md

@@ -404,7 +404,7 @@ Header Changes:
   * If you used files as views with `seqan3::views::get<seqan3::field::id>` to project a single field, e.g.
     * `seqan3::views::get<seqan3::field::id>(fin)` => `std::views::transform(fin, [](auto && record){ return record.id(); })`
     * `fin | seqan3::views::get<seqan3::field::id>()` => `fin | std::views::transform([](auto && record){ return record.id(); })`
-    * or per projection: `fin | std::views::transform(&decltype(fin)::record_type::id)`
+    * or per projection: `fin | std::views::transform(&decltype(fin)::%record_type::id)`
   * `seqan3::sequence_record`:
     * `seqan3::get<seqan3::field::id>(record)` => `record.id()`
     * `seqan3::get<seqan3::field::seq>(record)` => `record.sequence()`

doc/tutorial/08_pairwise_alignment/index.md

@@ -92,7 +92,7 @@ possibilities.
 The configuration object is the core of the alignment interface. It allows to easily configure the alignment algorithm
 without changing the interface of the pairwise alignment. It uses a seqan3::configuration object to chain different
 configuration elements together using the logical or-operator ('|'-operator).
-You can find an overview over the available configurations \ref configuration "here".
+You can find an overview over the available configurations \ref seqan3::configuration "here".
 The configurations for the alignment module are available in:
 
 \snippet doc/tutorial/08_pairwise_alignment/configurations.cpp include
@@ -335,7 +335,7 @@ You can use the std::views::filter to get only those alignments that fit the req
 Chaining the configurations to build an individual alignment algorithm is a strong advantage of this design. However,
 some combinations would result in an invalid alignment configuration. To explicitly prevent this we added some security
 details. First, if a combination is invalid (for example by providing the same configuration more than once) a static
-assert will inform you about the invalid combination. \ref configuration "Here" you can find a
+assert will inform you about the invalid combination. \ref seqan3::configuration "Here" you can find a
 table depicting the valid configurations. Further, if the seqan3::align_pairwise is called, it checks if the input
 data can be used with the given configuration. For example, a static assertion is emitted if the alphabet types of the
 sequences together with the provided scoring scheme do not model the concept seqan3::scoring_scheme_for.

include/seqan3/alignment/scoring/scoring_scheme_base.hpp

@@ -219,7 +219,7 @@ class scoring_scheme_base
         return matrix[to_rank(static_cast<alphabet_t>(alph1))][to_rank(static_cast<alphabet_t>(alph2))];
     }
 
-    //!\copydoc score
+    //!\copydoc seqan3::scoring_scheme_base::score
     template <typename alph1_t, typename alph2_t>
         requires explicitly_convertible_to<alph1_t, alphabet_t> && explicitly_convertible_to<alph2_t, alphabet_t>
     constexpr score_t score(alph1_t const alph1, alph2_t const alph2) const noexcept

include/seqan3/alphabet/composite/alphabet_tuple_base.hpp

@@ -357,7 +357,7 @@ class alphabet_tuple_base :
         return component_proxy<t, index>{val, l};
     }
 
-    /*!\copybrief get
+    /*!\copybrief seqan3::alphabet_tuple_base::get
      * \tparam type Return the element of specified type; only available if the type is unique in the set of components.
      * \returns A proxy to the contained element that models the same alphabets concepts and supports assignment.
      *
@@ -370,7 +370,7 @@ class alphabet_tuple_base :
         return get<seqan3::list_traits::find<type, component_list>>(l);
     }
 
-    /*!\copybrief get
+    /*!\copybrief seqan3::alphabet_tuple_base::get
      * \tparam index Return the i-th element.
      * \returns A copy of the contained element.
      *
@@ -386,7 +386,7 @@ class alphabet_tuple_base :
         return seqan3::assign_rank_to(l.to_component_rank<index>(), t{});
     }
 
-    /*!\copybrief get
+    /*!\copybrief seqan3::alphabet_tuple_base::get
      * \tparam type Return the element of specified type; only available if the type is unique in the set of components.
      * \returns A copy of the contained element.
      *
@@ -441,7 +441,7 @@ class alphabet_tuple_base :
         return get<component_type>(lhs) == rhs;
     }
 
-    //!\copydoc operator==(derived_type_t const lhs, indirect_component_type const rhs)
+    //!\copydoc seqan3::alphabet_tuple_base::operator==(derived_type_t const lhs, indirect_component_type const rhs)
     template <typename derived_type_t, typename indirect_component_type>
     friend constexpr auto operator==(indirect_component_type const lhs, derived_type_t const rhs) noexcept
         -> std::enable_if_t<
@@ -451,7 +451,7 @@ class alphabet_tuple_base :
         return rhs == lhs;
     }
 
-    //!\copydoc operator==(derived_type_t const lhs, indirect_component_type const rhs)
+    //!\copydoc seqan3::alphabet_tuple_base::operator==(derived_type_t const lhs, indirect_component_type const rhs)
     template <typename derived_type_t, typename indirect_component_type>
     friend constexpr auto operator!=(derived_type_t const lhs, indirect_component_type const rhs) noexcept
         -> std::enable_if_t<
@@ -465,7 +465,7 @@ class alphabet_tuple_base :
         return get<component_type>(lhs) != rhs;
     }
 
-    //!\copydoc operator==(derived_type_t const lhs, indirect_component_type const rhs)
+    //!\copydoc seqan3::alphabet_tuple_base::operator==(derived_type_t const lhs, indirect_component_type const rhs)
     template <typename derived_type_t, typename indirect_component_type>
     friend constexpr auto operator!=(indirect_component_type const lhs, derived_type_t const rhs) noexcept
         -> std::enable_if_t<
@@ -475,7 +475,7 @@ class alphabet_tuple_base :
         return rhs != lhs;
     }
 
-    //!\copydoc operator==(derived_type_t const lhs, indirect_component_type const rhs)
+    //!\copydoc seqan3::alphabet_tuple_base::operator==(derived_type_t const lhs, indirect_component_type const rhs)
     template <typename derived_type_t, typename indirect_component_type>
     friend constexpr auto operator<(derived_type_t const lhs, indirect_component_type const rhs) noexcept
         -> std::enable_if_t<
@@ -489,7 +489,7 @@ class alphabet_tuple_base :
         return get<component_type>(lhs) < rhs;
     }
 
-    //!\copydoc operator==(derived_type_t const lhs, indirect_component_type const rhs)
+    //!\copydoc seqan3::alphabet_tuple_base::operator==(derived_type_t const lhs, indirect_component_type const rhs)
     template <typename derived_type_t, typename indirect_component_type>
     friend constexpr auto operator<(indirect_component_type const lhs, derived_type_t const rhs) noexcept
         -> std::enable_if_t<
@@ -499,7 +499,7 @@ class alphabet_tuple_base :
         return rhs > lhs;
     }
 
-    //!\copydoc operator==(derived_type_t const lhs, indirect_component_type const rhs)
+    //!\copydoc seqan3::alphabet_tuple_base::operator==(derived_type_t const lhs, indirect_component_type const rhs)
     template <typename derived_type_t, typename indirect_component_type>
     friend constexpr auto operator<=(derived_type_t const lhs, indirect_component_type const rhs) noexcept
         -> std::enable_if_t<
@@ -513,7 +513,7 @@ class alphabet_tuple_base :
         return get<component_type>(lhs) <= rhs;
     }
 
-    //!\copydoc operator==(derived_type_t const lhs, indirect_component_type const rhs)
+    //!\copydoc seqan3::alphabet_tuple_base::operator==(derived_type_t const lhs, indirect_component_type const rhs)
     template <typename derived_type_t, typename indirect_component_type>
     friend constexpr auto operator<=(indirect_component_type const lhs, derived_type_t const rhs) noexcept
         -> std::enable_if_t<
@@ -523,7 +523,7 @@ class alphabet_tuple_base :
         return rhs >= lhs;
     }
 
-    //!\copydoc operator==(derived_type_t const lhs, indirect_component_type const rhs)
+    //!\copydoc seqan3::alphabet_tuple_base::operator==(derived_type_t const lhs, indirect_component_type const rhs)
     template <typename derived_type_t, typename indirect_component_type>
     friend constexpr auto operator>(derived_type_t const lhs, indirect_component_type const rhs) noexcept
         -> std::enable_if_t<
@@ -537,7 +537,7 @@ class alphabet_tuple_base :
         return get<component_type>(lhs) > rhs;
     }
 
-    //!\copydoc operator==(derived_type_t const lhs, indirect_component_type const rhs)
+    //!\copydoc seqan3::alphabet_tuple_base::operator==(derived_type_t const lhs, indirect_component_type const rhs)
     template <typename derived_type_t, typename indirect_component_type>
     friend constexpr auto operator>(indirect_component_type const lhs, derived_type_t const rhs) noexcept
         -> std::enable_if_t<
@@ -547,7 +547,7 @@ class alphabet_tuple_base :
         return rhs < lhs;
     }
 
-    //!\copydoc operator==(derived_type_t const lhs, indirect_component_type const rhs)
+    //!\copydoc seqan3::alphabet_tuple_base::operator==(derived_type_t const lhs, indirect_component_type const rhs)
     template <typename derived_type_t, typename indirect_component_type>
     friend constexpr auto operator>=(derived_type_t const lhs, indirect_component_type const rhs) noexcept
         -> std::enable_if_t<
@@ -561,7 +561,7 @@ class alphabet_tuple_base :
         return get<component_type>(lhs) >= rhs;
     }
 
-    //!\copydoc operator==(derived_type_t const lhs, indirect_component_type const rhs)
+    //!\copydoc seqan3::alphabet_tuple_base::operator==(derived_type_t const lhs, indirect_component_type const rhs)
     template <typename derived_type_t, typename indirect_component_type>
     friend constexpr auto operator>=(indirect_component_type const lhs, derived_type_t const rhs) noexcept
         -> std::enable_if_t<

include/seqan3/alphabet/container/bitpacked_sequence.hpp

@@ -1012,7 +1012,7 @@ class bitpacked_sequence
         std::swap(data, rhs.data);
     }
 
-    //!\copydoc swap()
+    //!\copydoc seqan3::bitpacked_sequence::swap
     constexpr void swap(bitpacked_sequence && rhs) noexcept
     {
         std::swap(data, rhs.data);

include/seqan3/io/sam_file/format_bam.hpp

@@ -161,81 +161,85 @@ class format_bam : private detail::format_sam_base
         int32_t tlen;             //!< The template length of the read and its mate.
     };
 
+    // clang-format off
     //!\brief Converts a cigar op character to the rank according to the official BAM specifications.
-    static constexpr std::array<uint8_t, 256> char_to_sam_rank{[]() constexpr {std::array<uint8_t, 256> ret{};
-
-    using index_t = std::make_unsigned_t<char>;
-
-    // ret['M'] = 0; set anyway by initialization
-    ret[static_cast<index_t>('I')] = 1;
-    ret[static_cast<index_t>('D')] = 2;
-    ret[static_cast<index_t>('N')] = 3;
-    ret[static_cast<index_t>('S')] = 4;
-    ret[static_cast<index_t>('H')] = 5;
-    ret[static_cast<index_t>('P')] = 6;
-    ret[static_cast<index_t>('=')] = 7;
-    ret[static_cast<index_t>('X')] = 8;
-
-    return ret;
-}()
-}; // namespace seqan3
-
-//!\brief Computes the bin number for a given region [beg, end), copied from the official SAM specifications.
-static uint16_t reg2bin(int32_t beg, int32_t end) noexcept
-{
-    --end;
-    if (beg >> 14 == end >> 14)
-        return ((1 << 15) - 1) / 7 + (beg >> 14);
-    if (beg >> 17 == end >> 17)
-        return ((1 << 12) - 1) / 7 + (beg >> 17);
-    if (beg >> 20 == end >> 20)
-        return ((1 << 9) - 1) / 7 + (beg >> 20);
-    if (beg >> 23 == end >> 23)
-        return ((1 << 6) - 1) / 7 + (beg >> 23);
-    if (beg >> 26 == end >> 26)
-        return ((1 << 3) - 1) / 7 + (beg >> 26);
-    return 0;
-}
+    static constexpr std::array<uint8_t, 256> char_to_sam_rank
+    {
+        []() constexpr {
+            std::array<uint8_t, 256> ret{};
+
+            using index_t = std::make_unsigned_t<char>;
+
+            // ret['M'] = 0; set anyway by initialization
+            ret[static_cast<index_t>('I')] = 1;
+            ret[static_cast<index_t>('D')] = 2;
+            ret[static_cast<index_t>('N')] = 3;
+            ret[static_cast<index_t>('S')] = 4;
+            ret[static_cast<index_t>('H')] = 5;
+            ret[static_cast<index_t>('P')] = 6;
+            ret[static_cast<index_t>('=')] = 7;
+            ret[static_cast<index_t>('X')] = 8;
+
+            return ret;
+        }()
+    };
+    // clang-format on
+
+    //!\brief Computes the bin number for a given region [beg, end), copied from the official SAM specifications.
+    static uint16_t reg2bin(int32_t beg, int32_t end) noexcept
+    {
+        --end;
+        if (beg >> 14 == end >> 14)
+            return ((1 << 15) - 1) / 7 + (beg >> 14);
+        if (beg >> 17 == end >> 17)
+            return ((1 << 12) - 1) / 7 + (beg >> 17);
+        if (beg >> 20 == end >> 20)
+            return ((1 << 9) - 1) / 7 + (beg >> 20);
+        if (beg >> 23 == end >> 23)
+            return ((1 << 6) - 1) / 7 + (beg >> 23);
+        if (beg >> 26 == end >> 26)
+            return ((1 << 3) - 1) / 7 + (beg >> 26);
+        return 0;
+    }
 
-/*!\brief Reads a arithmetic field from binary stream by directly reinterpreting the bits.
+    /*!\brief Reads a arithmetic field from binary stream by directly reinterpreting the bits.
      * \tparam stream_view_type  The type of the stream as a view.
      * \tparam number_type       The type of number to parse; must model std::integral.
      * \param[in, out] stream_view  The stream view to read from.
      * \param[out]     target       An integral value to store the parsed value in.
      */
-template <typename stream_view_type, std::integral number_type>
-void read_integral_byte_field(stream_view_type && stream_view, number_type & target)
-{
-    std::ranges::copy_n(std::ranges::begin(stream_view), sizeof(target), reinterpret_cast<char *>(&target));
-}
+    template <typename stream_view_type, std::integral number_type>
+    void read_integral_byte_field(stream_view_type && stream_view, number_type & target)
+    {
+        std::ranges::copy_n(std::ranges::begin(stream_view), sizeof(target), reinterpret_cast<char *>(&target));
+    }
 
-/*!\brief Reads a float field from binary stream by directly reinterpreting the bits.
+    /*!\brief Reads a float field from binary stream by directly reinterpreting the bits.
      * \tparam stream_view_type  The type of the stream as a view.
      * \param[in, out] stream_view  The stream view to read from.
      * \param[out]     target       An float value to store the parsed value in.
      */
-template <typename stream_view_type>
-void read_float_byte_field(stream_view_type && stream_view, float & target)
-{
-    std::ranges::copy_n(std::ranges::begin(stream_view), sizeof(int32_t), reinterpret_cast<char *>(&target));
-}
+    template <typename stream_view_type>
+    void read_float_byte_field(stream_view_type && stream_view, float & target)
+    {
+        std::ranges::copy_n(std::ranges::begin(stream_view), sizeof(int32_t), reinterpret_cast<char *>(&target));
+    }
 
-template <typename stream_view_type, typename value_type>
-void read_sam_dict_vector(seqan3::detail::sam_tag_variant & variant,
-                          stream_view_type && stream_view,
-                          value_type const & SEQAN3_DOXYGEN_ONLY(value));
+    template <typename stream_view_type, typename value_type>
+    void read_sam_dict_vector(seqan3::detail::sam_tag_variant & variant,
+                              stream_view_type && stream_view,
+                              value_type const & SEQAN3_DOXYGEN_ONLY(value));
 
-template <typename stream_view_type>
-void read_sam_dict_field(stream_view_type && stream_view, sam_tag_dictionary & target);
+    template <typename stream_view_type>
+    void read_sam_dict_field(stream_view_type && stream_view, sam_tag_dictionary & target);
 
-template <typename cigar_input_type>
-auto parse_binary_cigar(cigar_input_type && cigar_input, uint16_t n_cigar_op) const;
+    template <typename cigar_input_type>
+    auto parse_binary_cigar(cigar_input_type && cigar_input, uint16_t n_cigar_op) const;
 
-static std::string get_tag_dict_str(sam_tag_dictionary const & tag_dict);
-}
-;
+    static std::string get_tag_dict_str(sam_tag_dictionary const & tag_dict);
+};
 
-//!\copydoc sam_file_input_format::read_alignment_record
+//!\copydoc seqan3::sam_file_input_format::read_alignment_record
 template <typename stream_type, // constraints checked by file
           typename seq_legal_alph_type,
           typename ref_seqs_type,
@@ -628,7 +632,7 @@ format_bam::read_alignment_record(stream_type & stream,
         std::swap(cigar_vector, tmp_cigar_vector);
 }
 
-//!\copydoc sam_file_output_format::write_alignment_record
+//!\copydoc seqan3::sam_file_output_format::write_alignment_record
 template <typename stream_type,
           typename header_type,
           typename seq_type,

include/seqan3/io/sam_file/input_format_concept.hpp

@@ -147,6 +147,13 @@ concept sam_file_input_format = requires (detail::sam_file_input_format_exposer<
                                 };
 //!\endcond
 
+// Workaround for https://github.com/doxygen/doxygen/issues/9379
+#if SEQAN3_DOXYGEN_ONLY(1) 0
+template <typename t>
+class sam_file_input_format
+{};
+#endif
+
 /*!\name Requirements for seqan3::sam_file_input_format
  * \brief You can expect these **members** on all types that implement seqan3::sam_file_input_format.
  * \memberof seqan3::sam_file_input_format

include/seqan3/io/sam_file/output_format_concept.hpp

@@ -119,6 +119,13 @@ concept sam_file_output_format = requires (detail::sam_file_output_format_expose
                                  };
 //!\endcond
 
+// Workaround for https://github.com/doxygen/doxygen/issues/9379
+#if SEQAN3_DOXYGEN_ONLY(1) 0
+template <typename t>
+class sam_file_output_format
+{};
+#endif
+
 /*!\name Requirements for seqan3::sam_file_output_format
  * \brief You can expect these **members** on all types that implement seqan3::sam_file_output_format.
  * \memberof seqan3::sam_file_output_format

include/seqan3/io/sequence_file/input_format_concept.hpp

@@ -92,6 +92,13 @@ concept sequence_file_input_format =
     };
 //!\endcond
 
+// Workaround for https://github.com/doxygen/doxygen/issues/9379
+#if SEQAN3_DOXYGEN_ONLY(1) 0
+template <typename t>
+class sequence_file_input_format
+{};
+#endif
+
 /*!\name Requirements for seqan3::sequence_file_input_format
  * \brief You can expect these **members** on all types that implement seqan3::sequence_file_input_format.
  * \memberof seqan3::sequence_file_input_format

include/seqan3/io/sequence_file/output_format_concept.hpp

@@ -90,6 +90,13 @@ concept sequence_file_output_format = requires (detail::sequence_file_output_for
                                       };
 //!\endcond
 
+// Workaround for https://github.com/doxygen/doxygen/issues/9379
+#if SEQAN3_DOXYGEN_ONLY(1) 0
+template <typename t>
+class sequence_file_output_format
+{};
+#endif
+
 /*!\name Requirements for seqan3::sequence_file_output_format
  * \brief You can expect these **members** on all types that implement seqan3::sequence_file_output_format.
  * \memberof seqan3::sequence_file_output_format

include/seqan3/io/structure_file/input_format_concept.hpp

@@ -135,6 +135,13 @@ concept structure_file_input_format =
     };
 //!\endcond
 
+// Workaround for https://github.com/doxygen/doxygen/issues/9379
+#if SEQAN3_DOXYGEN_ONLY(1) 0
+template <typename t>
+class structure_file_input_format
+{};
+#endif
+
 /*!\name Requirements for seqan3::structure_file_input_format
  * \brief You can expect these **members** on all types that implement seqan3::structure_file_input_format.
  * \memberof seqan3::structure_file_input_format