Merge pull request #103 from h-2/documentation/views

Documentation/views

include/seqan3/range/concept.hpp

@@ -44,68 +44,93 @@
 
 namespace seqan3
 {
-/*!\name Range concepts
- * \brief Adapted from the Ranges TS.
- * \ingroup range
+/*!\addtogroup range
  * \{
  */
-/*!\brief Defines the requirements of a type that allows iteration over its elements by providing a begin iterator
+/*!\interface seqan3::range_concept <>
+ * \brief Defines the requirements of a type that allows iteration over its elements by providing a begin iterator
  * and an end sentinel.
  * \sa http://en.cppreference.com/w/cpp/experimental/ranges/iterator/Range
  */
+//!\cond
 template <typename type>
 concept bool range_concept               = (bool)ranges::Range<type>();
+//!\endcond
 
-/* these are independent specializations of range_concept */
-
-/*!\brief Specifies the requirements of a Range type that knows its size in constant time with the size function.
+/*!\interface seqan3::sized_range_concept <>
+ * \extends seqan3::range_concept
+ * \brief Specifies the requirements of a Range type that knows its size in constant time with the size function.
  * \sa http://en.cppreference.com/w/cpp/experimental/ranges/iterator/SizedRange
  */
+//!\cond
 template <typename type>
 concept bool sized_range_concept         = range_concept<type> && (bool)ranges::SizedRange<type>();
+//!\endcond
 
-/*!\brief Specifies requirements of a Range type for which `begin` and `end` return objects of the same type.
+/*!\interface seqan3::bounded_range_concept <>
+ * \extends seqan3::range_concept
+ * \brief Specifies requirements of a Range type for which `begin` and `end` return objects of the same type.
  * \sa http://en.cppreference.com/w/cpp/experimental/ranges/iterator/BoundedRange
  */
+//!\cond
 template <typename type>
 concept bool bounded_range_concept       = range_concept<type> && (bool)ranges::BoundedRange<type>();
+//!\endcond
 
-/*!\brief Specifies requirements of a Range type for which `begin` returns a type that satisfies
+/*!\interface seqan3::output_range_concept <>
+ * \extends seqan3::range_concept
+ * \brief Specifies requirements of a Range type for which `begin` returns a type that satisfies
  * seqan3::output_iterator_concept.
  * \sa http://en.cppreference.com/w/cpp/experimental/ranges/iterator/OutputRange
  */
+//!\cond
 template <typename type, typename out_type>
 concept bool output_range_concept        = range_concept<type> && (bool)ranges::OutputRange<type, out_type>();
+//!\endcond
 
-/* the following specialize incrementally */
-
-/*!\brief Specifies requirements of an Range type for which `begin` returns a type that satisfies
+/*!\interface seqan3::input_range_concept <>
+ * \extends seqan3::range_concept
+ * \brief Specifies requirements of an Range type for which `begin` returns a type that satisfies
  * seqan3::input_iterator_concept.
  * \sa http://en.cppreference.com/w/cpp/experimental/ranges/iterator/InputRange
  */
+//!\cond
 template <typename type>
 concept bool input_range_concept         = range_concept<type> && (bool)ranges::InputRange<type>();
+//!\endcond
 
-/*!\brief Specifies requirements of an Range type for which `begin` returns a type that satisfies
+/*!\interface seqan3::forward_range_concept <>
+ * \extends seqan3::input_range_concept
+ * \brief Specifies requirements of an Range type for which `begin` returns a type that satisfies
  * seqan3::forward_iterator_concept.
  * \sa http://en.cppreference.com/w/cpp/experimental/ranges/iterator/ForwardRange
  */
+//!\cond
 template <typename type>
 concept bool forward_range_concept       = input_range_concept<type> && (bool)ranges::ForwardRange<type>();
+//!\endcond
 
-/*!\brief Specifies requirements of an Range type for which `begin` returns a type that satisfies
+/*!\interface seqan3::bidirectional_range_concept <>
+ * \extends seqan3::forward_range_concept
+ * \brief Specifies requirements of an Range type for which `begin` returns a type that satisfies
  * seqan3::bidirectional_iterator_concept.
  * \sa http://en.cppreference.com/w/cpp/experimental/ranges/iterator/BidirectionalRange
  */
+//!\cond
 template <typename type>
 concept bool bidirectional_range_concept = forward_range_concept<type> && (bool)ranges::BidirectionalRange<type>();
+//!\endcond
 
-/*!\brief Specifies requirements of an Range type for which `begin` returns a type that satisfies
+/*!\interface seqan3::random_access_range_concept <>
+ * \extends seqan3::bidirectional_range_concept
+ * \brief Specifies requirements of an Range type for which `begin` returns a type that satisfies
  * seqan3::random_access_iterator_concept.
  * \sa http://en.cppreference.com/w/cpp/experimental/ranges/iterator/RandomAccessRange
  */
+//!\cond
 template <typename type>
 concept bool random_access_range_concept = bidirectional_range_concept<type> && (bool)ranges::RandomAccessRange<type>();
+//!\endcond
 
 //!\}
 } // namespace seqan3

include/seqan3/range/container/concatenated_sequences.hpp

@@ -61,6 +61,7 @@ namespace seqan3
  * \tparam inner_type The type of sequences that will be stored. Must satisfy seqan3::reservable_sequence_concept.
  * \tparam data_delimiters_type A container that stores the begin/end positions in the inner_type. Must be
  * seqan3::reservable_sequence_concept and have inner_type's size_type as value_type.
+ * \implements seqan3::reservable_sequence_concept
  *
  * This class may be used whenever you would usually use `std::vector<std::vector<some_alphabet>>` or
  * `std::vector<std::string>`, i.e. whenever you have a collection of sequences. It is the spiritual successor of
@@ -1287,6 +1288,5 @@ class concatenated_sequences
 
 #ifndef NDEBUG
 static_assert(seqan3::reservable_sequence_concept<seqan3::concatenated_sequences<std::string>>);
-static_assert(seqan3::ra_sequence_of_ra_sequence_concept<seqan3::concatenated_sequences<std::string>>);
 static_assert(seqan3::forward_range_concept<seqan3::concatenated_sequences<std::string>>);
 #endif

include/seqan3/range/container/concept.hpp

@@ -45,19 +45,22 @@
 namespace seqan3
 {
 
-/*!\name Container concepts
- * \brief Container concepts as defined by the standard library (or very close).
- * \ingroup container
+/*!\addtogroup container
  * \{
  */
-/*!\brief The (most general) container concept as defined by the standard library.
+/*!\interface seqan3::container_concept <>
+ * \extends seqan3::forward_range_concept
+ * \extends seqan3::sized_range_concept
+ * \extends seqan3::bounded_range_concept
+ * \brief The (most general) container concept as defined by the standard library.
  * \details
  * The container concept is modelled exactly as in the [STL](http://en.cppreference.com/w/cpp/concept/Container).
  *
  * \attention
  * Other than one might expect, `std::forward_list` does not satisfy this concept (because it does not provide
  * `.size()`).
  */
+//!\cond
 template <typename type>
 concept bool container_concept = requires (type val, type val2)
 {
@@ -91,8 +94,11 @@ concept bool container_concept = requires (type val, type val2)
     { val.max_size()  } -> typename type::size_type;
     { val.empty()     } -> bool;
 };
+//!\endcond
 
-/*!\brief A more refined container concept than seqan3::container_concept.
+/*!\interface seqan3::sequence_concept <>
+ * \extends seqan3::container_concept
+ * \brief A more refined container concept than seqan3::container_concept.
  *
  * Includes constraints on constructors, `assign()`, `.insert()`, `.erase()`, `.push_back()`, `.pop_back`, `.clear()`,
  * `.size()`, `front()` and `.back()` member functions with corresponding signatures. Models the subset of the
@@ -102,6 +108,7 @@ concept bool container_concept = requires (type val, type val2)
  * \attention
  * `std::array` and `std::forward_list` do not satisfy this concept.
  */
+//!\cond
 template <typename type>
 concept bool sequence_concept = requires (type val, type val2)
 {
@@ -138,16 +145,23 @@ concept bool sequence_concept = requires (type val, type val2)
     { val.front() } -> typename type::reference;
     { val.back()  } -> typename type::reference;
 };
+//!\endcond
 
-/*!\brief A more refined container concept than seqan3::sequence_concept.
+/*!\interface seqan3::random_access_sequence_concept <>
+ * \extends seqan3::sequence_concept
+ * \extends seqan3::random_access_range_concept
+ * \brief A more refined container concept than seqan3::sequence_concept.
  *
  * Adds requirements for `.at()`, `.resize()` and the subscript operator `[]`. Models the subset of the
  * [STL SequenceContainerConcept](http://en.cppreference.com/w/cpp/concept/SequenceContainer) that is supported
  * by `std::vector`, `std::deque` and `std::basic_string`.
  *
  * \attention
  * `std::array`, `std::forward_list` and `std::list` do not satisfy this concept.
+ *
+ * \sa
  */
+//!\cond
 template <typename type>
 concept bool random_access_sequence_concept = requires (type val)
 {
@@ -161,14 +175,19 @@ concept bool random_access_sequence_concept = requires (type val)
     { val.resize(0)                              } -> void;
     { val.resize(0, typename type::value_type{}) } -> void;
 };
+//!\endcond
 
-/*!\brief A more refined container concept than seqan3::random_access_sequence_concept.
+/*!\interface seqan3::reservable_sequence_concept <>
+ * \extends seqan3::random_access_sequence_concept
+ * \brief A more refined container concept than seqan3::random_access_sequence_concept.
  *
- * Adds requirements for `.reserve()`. Satisfied by `std::vector` and `std::basic_string`.
+ * Adds requirements for `.reserve()`, `.capacity()` and `.shrink_to_fit()`.
+ * Satisfied by `std::vector` and `std::basic_string`.
  *
  * \attention
  * `std::array`, `std::forward_list`, `std::list` and `std::deque` do not satisfy this concept.
  */
+//!\cond
 template <typename type>
 concept bool reservable_sequence_concept = requires (type val)
 {
@@ -178,46 +197,8 @@ concept bool reservable_sequence_concept = requires (type val)
     { val.reserve(0)      } -> void;
     { val.shrink_to_fit() } -> void;
 };
-//!\}
-
-/*!\name Container-of-container concepts
- * \brief Shortcuts for multi-dimensional container concepts.
- * \ingroup container
- * \{
- */
-/*!\brief A multi-dimensional seqan3::container_concept.
- *
- * Requires that both the type and it's `value_type` fulfill seqan3::container_concept.
- */
-template <typename type>
-concept bool container_of_container_concept = requires (type val)
-{
-    requires container_concept<type>;
-    requires container_concept<typename type::value_type>;
-};
-
-/*!\brief A multi-dimensional seqan3::sequence_concept.
- *
- * Requires that both the type and it's `value_type` fulfill seqan3::sequence_concept.
- */
-template <typename type>
-concept bool sequence_of_sequence_concept = requires (type val)
-{
-    requires sequence_concept<type>;
-    requires sequence_concept<typename type::value_type>;
-};
-
-/*!\brief A multi-dimensional seqan3::random_access_sequence_concept
- *
- * Requires that both the type and it's `value_type` fulfill seqan3::random_access_sequence_concept.
- */
+//!\endcond
 
-template <typename type>
-concept bool ra_sequence_of_ra_sequence_concept = requires (type val)
-{
-    requires random_access_sequence_concept<type>;
-    requires random_access_sequence_concept<typename type::value_type>;
-};
 //!\}
 
 } // namespace seqan3
@@ -238,10 +219,6 @@ static_assert(seqan3::random_access_sequence_concept<std::vector<char>>);
 static_assert(seqan3::random_access_sequence_concept<std::deque<char>>);
 static_assert(seqan3::random_access_sequence_concept<std::string>);
 
-static_assert(seqan3::container_of_container_concept<std::array<std::array<char, 2>, 2>>);
-static_assert(seqan3::sequence_of_sequence_concept<std::list<std::list<char>>>);
-static_assert(seqan3::ra_sequence_of_ra_sequence_concept<std::vector<std::vector<char>>>);
-
 /* Check the SDSL containers */
 //TODO