Add some basic intro text to the iter namespace for now

Author: danakj

sus/collections/collections.h

@@ -246,7 +246,7 @@ namespace sus {
 /// # Ranges
 /// The collections in the Subspace C++ library can be used with standard ranges
 /// by calling the [`range()`]($sus::iter::IteratorBase::range) adaptor on any
-/// Subspace iterator. It will return an object that satisfies
+/// [`Iterator`]($sus::iter::Iterator). It will return an object that satisfies
 /// [`std::ranges::input_range`](https://en.cppreference.com/w/cpp/ranges/input_range)
 /// and
 /// [`std::ranges::viewable_range`](https://en.cppreference.com/w/cpp/ranges/viewable_range),
@@ -257,8 +257,9 @@ namespace sus {
 /// [`std::ranges::output_range`](https://en.cppreference.com/w/cpp/ranges/input_range),
 /// such as with `vec.iter_mut().range()`.
 ///
-/// Conversely, standard ranges, such as the types in the standard containers
-/// library, can be used to construct a Subspace iterator through
+/// Conversely, an [`Iterator`]($sus::iter::Iterator) can be constructed for
+/// a standard range such as [`std::vector`](
+/// https://en.cppreference.com/w/cpp/container/vector) through
 /// [`sus::iter::from_range`]($sus::iter::from_range).
 ///
 /// # Familiarity with Rust APIs

sus/iter/iterator.h

@@ -14,6 +14,32 @@
 
 #pragma once
 
+namespace sus {
+
+/// Composable external iteration.
+///
+/// If you've found yourself with a collection of some kind, and needed to
+/// perform an operation on the elements of said collection, you'll quickly run
+/// into 'iterators'. Iterators are heavily used in idiomatic Rust code, so
+/// it's worth becoming familiar with them.
+///
+/// The use of iterators with collections is described in [the collections
+/// documentation]($sus::collections#iterators).
+///
+/// TODO: Write lots more here.
+///
+/// All iterators implement the [`Iterator`]($sus::iter::Iterator) concept. Part
+/// of implementing that requires inheriting from [`IteratorBase`](
+/// $sus::iter::IteratorBase) which provides a large number of methods for
+/// filtering or transforming the items produced by the iterator. All of these
+/// methods are "lazy" in that they construct a new iterator but do not touch
+/// the source which generates items until iteration begins.
+///
+/// Iterators can [interact with standard ranges]($sus::collections#ranges) as
+/// well.
+namespace iter {}
+}
+
 // IWYU pragma: begin_exports
 #include "sus/iter/iterator_defn.h"
 #include "sus/iter/iterator_impl.h"