API Stability seqan3.1

[marehr]

• ./alignment
• ./alphabet
• ./argument_parser NOAPI => Core meeting 2021-01-18: We want this out before 3.1
• ./contrib NOAPI
• ./core
• ./io
• ./range
• ./search
• ./std NOAPI
• ./utility NOAPI
• ./version.hpp; See Some minor changes to version.hpp #277
  • SEQAN3_VERSION_MAJOR
  • SEQAN3_VERSION_MINOR
  • SEQAN3_VERSION_PATCH
  • SEQAN3_VERSION
  • seqan3_version_major
  • seqan3_version_minor
  • seqan3_version_patch
  • seqan3_version; see Resolution: API Stability seqan3.1 #274 (comment)

[marehr]

Core-Meeting 2021-01-11:

• NOAPI as they are marked
• ./version.hpp ( Some minor changes to version.hpp #277)
  • seqan3_version should be changed to have the same meaning as the macro
  • seqan3_version_cstring is the old seqan3_version, but as cstring (we need some macro vodoo to build that)
  • version.hpp should not include any other header
  • platform.hpp should include version.hpp

[marehr]

Core-Meeting 2021-01-11:

• Change default meaning:
  • user documentation:
    • no annotation means noapi (before we said that the default is experimental until 3.1 release, after that the default would have been public api)
    • no annotation is not encouraged, please annotate explicitly with your intended tag
• noapi: Mean no API, that means we don't guarantee that the signatures change, can be deleted, moved changed
  • noapi can be added to a whole namespace/class that means every member within that namespace/class is noapi
• experimental: Is public API, but we don't guarantee that the signatures change, this might become a stableapi, in this state it can be renamed, moved or deleted.
• stable: Is public API, and we guarantee that we don't change the signature. We are still allowed to break this, but this should be a real exception, see https://docs.seqan.de/seqan/3-master-user/about_api.html for what to do in this case
• deprecated: noapi/experimental/stable that will be removed

Doxygen:

• add tags
• \noapi (already exists),
• \experimentalapi (currently \experimental),
• \stableapi (must be added)

TODO:

• We need to figure out whether \noapi can be shown automatically by css hacks, if experimental or stableapi wasn't given
• add doxygen tags and update documentation ([DOC] Update API stability documentation #279)

Code Look-And-Feel:

/*!\brief ....
 * \noapi // shows in doxygen that this class is ... NOAPI
 * \experimentalapi // ... experimental
 * \stableapi // ... stable
 */
template </*SEQAN3_EXPERIMENTALAPI*/ typename derived_type, /*SEQAN3_EXPERIMENTALAPI*/ size_t size, /*SEQAN3_EXPERIMENTALAPI*/ typename char_t = char>
class SEQAN3_STABLEAPI SEQAN3_DEPRECATED_310 alphabet_base : public base, private base2, protected base3
{
public:
   //!\brief Blah \stableapi
   alphabet_base SEQAN3_STABLEAPI () = default;

   //!\brief Blah \stableapi{models std::input_iterator} \hideinitializer
   using iterator = my_iterator_type;

   //!\brief Blah \stableapi
   using value_type = std::string;

   //!\brief Blah \experimentalapi
   using type2 SEQAN3_EXPERIMENTALAPI = double;

   //!\brief Blah
   int foo();

   //!\brief Blah \stableapi
   int var;
};

int main()
{
   using alphabet_t = alphabet_base; // guranteed, stable-api; alphabet_base name isn't allowed to change
   alphabet_base alphabet{}; // guranteed, stable-api; default constructor must be available
   typename alphabet_base::iterator; // guranteed, stable-api; meber type 'iterator' must be available, and must model std::input_iterator, but the implementing class can change (e.g. my_iterator_type could be exchanged by my_iterator_type2)
   typename alphabet_base::value_type; // guranteed, stable-api, value_type must be std::string and isn't allowed to change
   typename alphabet_base::type2: // experimental (by default, because no annotation)

   alphabet.var; // guranteed, stable-api
   alphabet.foo(); // is implicitly no-api, because it has no api label.
};

Whish-List:

• Macros SEQAN3_STABLEAPI, SEQAN3_EXPERIMENTALAPI, SEQAN3_NOAPI,
  • but only when we figured out how to automate creating lists with them non-annontated (clang-tool)
  • SEQAN3_EXPERIMENTALAPI and SEQAN3_NOAPI might be interesting for the user, as a "deprecation" warning, to see which API they use that are not stable yet.
• Doxygen tags should take optional messages, like \tutorial_head (see https://github.com/seqan/seqan3/blob/master/doc/tutorial/alphabet/index.md)
• doxygen should show api stability (e.g. experimental, no-api and stable)
  

[marehr]

Problems encountered:

Doxygen can't handle inherited constructors.

#if SEQAN3_DOXYGEN_ONLY(1)0
    //!\copydoc seqan3::aminoacid_base::aminoacid_base(other_aa_type const other)
    //!\sa seqan3::aminoacid_base::aminoacid_base(other_aa_type const other)
    explicit constexpr aminoacid_base(other_aa_type const other) noexcept;
#endif //SEQAN3_DOXYGEN_ONLY(1)0

We work-around this at some places, e.g. in cigar alphabet

    /*!\brief Construction via a value of one of the components.
     * \tparam component_type One of the component types; must be uniquely contained in the type list of the composite.
     * \param[in] alph        The value of a component that should be assigned.
     *
     * \include test/snippet/alphabet/cigar/cigar_value_construction.cpp
     */
    SEQAN3_DOXYGEN_ONLY(( constexpr cigar(component_type const alph) noexcept {} ))

https://github.com/seqan/seqan3/blob/810a135b37053940d469a03c62a6ca410865d5c0/include/seqan3/alphabet/cigar/cigar.hpp#L78-L84

• We disabled INLINE_INHERITED_MEMB [DOC] Enable section for inherited members seqan3#2387

[marehr]

From my POV done.