Merge 130fd6e into 87bb1e1

include/seqan3/alphabet/aminoacid/aa10li.hpp

@@ -76,6 +76,8 @@ namespace seqan3
  * BMC Genomics, 17, 366. https://doi.org/10.1186/s12864-016-2692-4
  *
  * \include test/snippet/alphabet/aminoacid/aa10li.cpp
+ *
+ * \stableapi{Since version 3.1.}
  */
 class aa10li : public aminoacid_base<aa10li, 10>
 {
@@ -164,8 +166,11 @@ class aa10li : public aminoacid_base<aa10li, 10>
 // containers
 // ------------------------------------------------------------------
 
-//!\brief Alias for an std::vector of seqan3::aa10li.
-//!\relates aa10li
+/*!\brief Alias for an std::vector of seqan3::aa10li.
+ * \relates aa10li
+ *
+ * \stableapi{Since version 3.1.}
+ */
 using aa10li_vector = std::vector<aa10li>;
 
 // ------------------------------------------------------------------

include/seqan3/alphabet/aminoacid/aa10murphy.hpp

@@ -75,6 +75,8 @@ namespace seqan3
  * BMC Genomics, 17, 366. https://doi.org/10.1186/s12864-016-2692-4
  *
  * \include test/snippet/alphabet/aminoacid/aa10murphy.cpp
+ *
+ * \stableapi{Since version 3.1.}
  */
 class aa10murphy : public aminoacid_base<aa10murphy, 10>
 {
@@ -163,8 +165,11 @@ class aa10murphy : public aminoacid_base<aa10murphy, 10>
 // containers
 // ------------------------------------------------------------------
 
-//!\brief Alias for an std::vector of seqan3::aa10murphy.
-//!\relates aa10murphy
+/*!\brief Alias for an std::vector of seqan3::aa10murphy.
+ * \relates aa10murphy
+ *
+ * \stableapi{Since version 3.1.}
+ */
 using aa10murphy_vector = std::vector<aa10murphy>;
 
 // ------------------------------------------------------------------
@@ -179,6 +184,8 @@ using aa10murphy_vector = std::vector<aa10murphy>;
  * \param[in] c The character to assign.
  * \relates seqan3::aa10murphy
  * \returns seqan3::aa10murphy
+ *
+ * \stableapi{Since version 3.1.}
  */
 constexpr aa10murphy operator""_aa10murphy(char const c) noexcept
 {
@@ -195,9 +202,10 @@ constexpr aa10murphy operator""_aa10murphy(char const c) noexcept
  *
  * \attention
  * All seqan3 literals are in the namespace seqan3!
+ *
+ * \stableapi{Since version 3.1.}
  */
-
-inline aa10murphy_vector operator""_aa10murphy(const char * s, std::size_t n)
+inline aa10murphy_vector operator""_aa10murphy(char const * const s, size_t const n)
 {
     aa10murphy_vector r;
     r.resize(n);

include/seqan3/alphabet/aminoacid/aa20.hpp

@@ -57,6 +57,8 @@ namespace seqan3
  * BMC Genomics, 17, 366. https://doi.org/10.1186/s12864-016-2692-4
  *
  * \include test/snippet/alphabet/aminoacid/aa20_construction.cpp
+ *
+ * \stableapi{Since version 3.1.}
  */
 class aa20 : public aminoacid_base<aa20, 20>
 {
@@ -148,8 +150,11 @@ class aa20 : public aminoacid_base<aa20, 20>
 
 namespace seqan3
 {
-//!\brief Alias for an std::vector of seqan3::aa20.
-//!\relates aa20
+/*!\brief Alias for an std::vector of seqan3::aa20.
+ * \relates aa20
+ *
+ * \stableapi{Since version 3.1.}
+ */
 using aa20_vector = std::vector<aa20>;
 
 } // namespace seqan3
@@ -172,6 +177,7 @@ namespace seqan3
  *
  * \include test/snippet/alphabet/aminoacid/aa20_char_literal.cpp
  *
+ * \stableapi{Since version 3.1.}
  */
 constexpr aa20 operator""_aa20(char const c) noexcept
 {
@@ -190,9 +196,10 @@ constexpr aa20 operator""_aa20(char const c) noexcept
  *
  * \attention
  * All seqan3 literals are in the namespace seqan3!
+ *
+ * \stableapi{Since version 3.1.}
  */
-
-inline aa20_vector operator""_aa20(const char * s, std::size_t n)
+inline aa20_vector operator""_aa20(char const * const s, size_t const n)
 {
     aa20_vector r;
     r.resize(n);

include/seqan3/alphabet/aminoacid/aa27.hpp

@@ -38,6 +38,8 @@ namespace seqan3
  * function seqan3::aa27::assign_char().
  *
  * \include test/snippet/alphabet/aminoacid/aa27_construction.cpp
+ *
+ * \stableapi{Since version 3.1.}
  */
 
 class aa27 : public aminoacid_base<aa27, 27>
@@ -130,8 +132,11 @@ class aa27 : public aminoacid_base<aa27, 27>
 
 namespace seqan3
 {
-//!\brief Alias for an std::vector of seqan3::aa27.
-//!\relates aa27
+/*!\brief Alias for an std::vector of seqan3::aa27.
+ * \relates aa27
+ *
+ * \stableapi{Since version 3.1.}
+ */
 using aa27_vector = std::vector<aa27>;
 
 } // namespace seqan3
@@ -154,6 +159,7 @@ namespace seqan3
  *
  * \include test/snippet/alphabet/aminoacid/aa27_char_literal.cpp
  *
+ * \stableapi{Since version 3.1.}
  */
 constexpr aa27 operator""_aa27(char const c) noexcept
 {
@@ -172,9 +178,10 @@ constexpr aa27 operator""_aa27(char const c) noexcept
  *
  * \attention
  * All seqan3 literals are in the namespace seqan3!
+ *
+ * \stableapi{Since version 3.1.}
  */
-
-inline aa27_vector operator""_aa27(const char * s, std::size_t n)
+inline aa27_vector operator""_aa27(char const * const s, size_t const n)
 {
     aa27_vector r;
     r.resize(n);

include/seqan3/alphabet/aminoacid/all.hpp

@@ -68,8 +68,6 @@
  * |    Unknown                 | Xaa               | X               | <span style="color:red">S</span>| <span style="color:red">S</span> | <span style="color:red">A</span> |
  * |    Stop Codon              | N/A               | *               | <span style="color:red">W</span>| <span style="color:red">F</span> | <span style="color:red">F</span> |
  *
- * All amino acid alphabets provide static value members (like an enum) for all amino acids in the form of the
- * one-letter representation.
  * As shown above, alphabets smaller than 27 internally represent multiple amino acids as one.\n
  * For most cases it is highly recommended to use seqan3::aa27 as seqan3::aa20 provides
  * no benefits in regard to space consumption (both need 5bits).

include/seqan3/alphabet/aminoacid/concept.hpp

@@ -28,6 +28,8 @@ namespace seqan3
 /*!\brief This is an empty base class that can be inherited by types that shall model seqan3::aminoacid_alphabet.
  * \ingroup aminoacid
  * \see seqan3::enable_aminoacid
+ *
+ * \stableapi{Since version 3.1.}
  */
 struct aminoacid_empty_base
 {};
@@ -89,16 +91,14 @@ namespace seqan3
  *
  * ### Specialisation
  *
- * Do not specialise this trait directly. It acts as a wrapper and looks for two possible implementations
+ * Do not specialise this trait directly. It acts as a wrapper and looks for three possible implementations
  * (in this order):
  *
  *   1. A `static` member variable `enable_aminoacid` of the class `seqan3::custom::alphabet<t>`.
  *   2. A free function `constexpr bool enable_aminoacid(t) noexcept` in the namespace of your type (or as `friend`).
- *
- * If none of these is found, the default value is defined as:
- *
- *   * `true` if the type inherits from seqan3::aminoacid_empty_base (or seqan3::aminoacid_base),
- *   * `false` otherwise.
+ *   3. If none of these is found, the default value is defined as:
+ *     * `true` if the type inherits from seqan3::aminoacid_empty_base (or seqan3::aminoacid_base),
+ *     * `false` otherwise.
  *
  * Implementations of 1. and 2. are required to be marked `constexpr` and the value / return value must be convertible
  * to `bool`.
@@ -118,6 +118,11 @@ namespace seqan3
  *
  * This is a customisation point (see \ref about_customisation). To change the default behaviour for your own alphabet,
  * follow the above instructions.
+ *
+ * \experimentalapi{Implementation 2 (free function) is not stable.}
+ *
+ * \stableapi{Since version 3.1. The name seqan3::enable_aminoacid, Implementation 1,
+ *            and Implementation 3 are stable and will not change.}
  */
 template <typename t>
 inline constexpr bool enable_aminoacid = detail::adl_only::enable_aminoacid_dispatcher::dispatch<std::remove_cvref_t<t>>();
@@ -138,6 +143,8 @@ inline constexpr bool enable_aminoacid = detail::adl_only::enable_aminoacid_disp
  * ###Concepts and doxygen
  * The requirements for this concept are given as related functions and type traits.
  * Types that satisfy this concept are shown as "implementing this interface".
+ *
+ * \stableapi{Since version 3.1.}
  */
 //!\cond
 template <typename type>

include/seqan3/alphabet/aminoacid/translation.hpp

@@ -32,7 +32,7 @@ class rna15;
 
 /*!\brief Translate one nucleotide triplet into single amino acid (single nucleotide interface).
  * \ingroup aminoacid
- * \tparam nucl_type The type of input nucleotides.
+ * \tparam nucl_type The type of input nucleotides; must model seqan3::nucleotide_alphabet.
  * \param[in] n1 First nucleotide in triplet.
  * \param[in] n2 Second nucleotide in triplet.
  * \param[in] n3 Third nucleotide in triplet.
@@ -48,8 +48,10 @@ class rna15;
  * ### Exceptions
  *
  * No-throw guarantee.
+ *
+ * \experimentalapi{Experimental since version 3.1.}
  */
-template <genetic_code gc = genetic_code::CANONICAL, nucleotide_alphabet nucl_type>
+template <genetic_code gc = genetic_code::canonical, nucleotide_alphabet nucl_type>
 constexpr aa27 translate_triplet(nucl_type const & n1, nucl_type const & n2, nucl_type const & n3) noexcept
 {
     if constexpr (std::same_as<nucl_type, dna4> || std::same_as<nucl_type, dna5> || std::same_as<nucl_type, dna15>)
@@ -95,7 +97,7 @@ constexpr aa27 translate_triplet(nucl_type const & n1, nucl_type const & n2, nuc
  *
  * \deprecated Use seqan3::translate_triplet(nucl_type const & n1, nucl_type const & n2, nucl_type const & n3) instead.
  */
-template <genetic_code gc = genetic_code::CANONICAL, typename tuple_type>
+template <genetic_code gc = genetic_code::canonical, typename tuple_type>
 //!\cond
     requires (std::tuple_size<tuple_type>::value == 3) &&
              nucleotide_alphabet<std::tuple_element_t<0, tuple_type>> &&
@@ -126,7 +128,7 @@ constexpr aa27 translate_triplet SEQAN3_DEPRECATED_310 (tuple_type const & input
  *
  * \deprecated Use seqan3::translate_triplet(nucl_type const & n1, nucl_type const & n2, nucl_type const & n3) instead.
  */
-template <genetic_code gc = genetic_code::CANONICAL, std::ranges::input_range range_type>
+template <genetic_code gc = genetic_code::canonical, std::ranges::input_range range_type>
 //!\cond
     requires nucleotide_alphabet<std::ranges::range_reference_t<std::decay_t<range_type>>>
 //!\endcond
@@ -162,7 +164,7 @@ constexpr aa27 translate_triplet SEQAN3_DEPRECATED_310 (range_type && input_rang
  *
  * \deprecated Use seqan3::translate_triplet(nucl_type const & n1, nucl_type const & n2, nucl_type const & n3) instead.
  */
-template <genetic_code gc = genetic_code::CANONICAL, std::ranges::random_access_range rng_t>
+template <genetic_code gc = genetic_code::canonical, std::ranges::random_access_range rng_t>
 //!\cond
     requires nucleotide_alphabet<std::ranges::range_reference_t<std::decay_t<rng_t>>>
 //!\endcond

include/seqan3/alphabet/aminoacid/translation_details.hpp

@@ -24,7 +24,7 @@ namespace seqan3::detail
  *
  * \details  All nucleotides are casted to dna15 and the dna15 translation table is used for translation.
  */
-template <typename nucl_type, seqan3::genetic_code gc = seqan3::genetic_code::CANONICAL, typename void_type = void>
+template <typename nucl_type, seqan3::genetic_code gc = seqan3::genetic_code::canonical, typename void_type = void>
 struct translation_table
 {
     //!\brief Holds the generic translation table.
@@ -57,7 +57,7 @@ struct translation_table
 
 //!\brief Translation table for canonical genetic code and dna15 alphabet.
 template <typename void_type>
-struct translation_table<dna15, seqan3::genetic_code::CANONICAL, void_type>
+struct translation_table<dna15, seqan3::genetic_code::canonical, void_type>
 {
     //!\brief Holds the translation table for canonical genetic code and nucl16 alphabet.
     static constexpr aa27 VALUE[dna15::alphabet_size][dna15::alphabet_size][dna15::alphabet_size]

include/seqan3/alphabet/aminoacid/translation_genetic_code.hpp

@@ -19,29 +19,32 @@ namespace seqan3
 /*!\brief Genetic codes used for translation of nucleotides into amino acids.
  *
  * \details
- * The numeric values of the enums correspond to the genbank transl_table values
- * (see https://www.ncbi.nlm.nih.gov/Taxonomy/Utils/wprintgc.cgi).
+ * The numeric values of the enums correspond to the genbank transl_table values.
+ * \sa https://www.ncbi.nlm.nih.gov/Taxonomy/Utils/wprintgc.cgi
+ *
+ * \experimentalapi{Experimental since version 3.1.}
  */
 enum struct genetic_code : uint8_t
 {
-    CANONICAL=1,
-//     VERT_MITOCHONDRIAL,
-//     YEAST_MITOCHONDRIAL,
-//     MOLD_MITOCHONDRIAL,
-//     INVERT_MITOCHONDRIAL,
-//     CILIATE,
-//     FLATWORM_MITOCHONDRIAL = 9,
-//     EUPLOTID,
-//     PROKARYOTE,
-//     ALT_YEAST,
-//     ASCIDIAN_MITOCHONDRIAL,
-//     ALT_FLATWORM_MITOCHONDRIAL,
-//     BLEPHARISMA,
-//     CHLOROPHYCEAN_MITOCHONDRIAL,
-//     TREMATODE_MITOCHONDRIAL = 21,
-//     SCENEDESMUS_MITOCHONDRIAL,
-//     THRAUSTOCHYTRIUM_MITOCHONDRIAL,
-//     PTEROBRANCHIA_MITOCHONDRIAL,
-//     GRACILIBACTERIA
+    canonical = 1, //!< [The Standard Code](https://www.ncbi.nlm.nih.gov/Taxonomy/Utils/wprintgc.cgi#SG1).
+    CANONICAL SEQAN3_DEPRECATED_310 = canonical, //!< \deprecated Use seqan3::genetic_code::canonical instead.
+//     vert_mitochondrial,
+//     yeast_mitochondrial,
+//     mold_mitochondrial,
+//     invert_mitochondrial,
+//     ciliate,
+//     flatworm_mitochondrial = 9,
+//     euplotid,
+//     prokaryote,
+//     alt_yeast,
+//     ascidian_mitochondrial,
+//     alt_flatworm_mitochondrial,
+//     blepharisma,
+//     chlorophycean_mitochondrial,
+//     trematode_mitochondrial = 21,
+//     scenedesmus_mitochondrial,
+//     thraustochytrium_mitochondrial,
+//     pterobranchia_mitochondrial,
+//     gracilibacteria
 };
 }