Address review feedback

doc/cpp/README.md

@@ -70,6 +70,7 @@ the repository at `gtirb/doc/examples/api-walkthrough.cpp`) for a
 basic introduction to using the GTIRB API in C++.
 
 ## Iteration Order
+\anchor iteration_order
 
 ### Blocks
 

include/gtirb/ByteInterval.hpp

@@ -353,35 +353,40 @@ class GTIRB_EXPORT_API ByteInterval : public Node {
 
   /// \brief Iterator over \ref Block objects.
   ///
-  /// Blocks are yielded in offset order, ascending. If two blocks have the
-  /// same offset, their order is not specified.
+  /// Blocks are yielded in offset order, ascending. For more details, see
+  /// \ref iteration_order "the documentation on iteration order".
+
   using block_iterator =
       boost::transform_iterator<BlockToNode<Node>,
                                 BlockSet::index<by_offset>::type::iterator>;
   /// \brief Range of \ref Block objects.
   ///
-  /// Blocks are yielded in offset order, ascending. If two blocks have the
-  /// same offset, their order is not specified.
+  /// Blocks are yielded in offset order, ascending. For more details, see
+  /// \ref iteration_order "the documentation on iteration order".
   using block_range = boost::iterator_range<block_iterator>;
   /// \brief Sub-range of blocks overlapping an address or range of addreses.
   ///
-  /// Blocks are yielded in offset order, ascending.
+  /// Blocks are yielded in offset order, ascending. For more details, see
+  /// \ref iteration_order "the documentation on iteration order".
   using block_subrange = boost::iterator_range<boost::transform_iterator<
       BlockToNode<Node>, BlockIntMap::codomain_type::iterator>>;
   /// \brief Const iterator over \ref Block objects.
   ///
-  /// Blocks are yielded in offset order, ascending.
+  /// Blocks are yielded in offset order, ascending. For more details, see
+  /// \ref iteration_order "the documentation on iteration order".
   using const_block_iterator = boost::transform_iterator<
       BlockToNode<const Node>,
       BlockSet::index<by_offset>::type::const_iterator>;
   /// \brief Const range of \ref Block objects.
   ///
-  /// Blocks are yielded in offset order, ascending.
+  /// Blocks are yielded in offset order, ascending. For more details, see
+  /// \ref iteration_order "the documentation on iteration order".
   using const_block_range = boost::iterator_range<const_block_iterator>;
   /// \brief Const sub-range of blocks overlapping an address or range of
   /// addreses.
   ///
-  /// Blocks are yielded in offset order, ascending.
+  /// Blocks are yielded in offset order, ascending. For more details, see
+  /// \ref iteration_order "the documentation on iteration order".
   using const_block_subrange = boost::iterator_range<boost::transform_iterator<
       BlockToNode<const Node>, BlockIntMap::codomain_type::const_iterator>>;
 
@@ -577,40 +582,46 @@ class GTIRB_EXPORT_API ByteInterval : public Node {
 
   /// \brief Iterator over \ref CodeBlock objects.
   ///
-  /// Blocks are yielded in offset order, ascending.
+  /// Blocks are yielded in offset order, ascending. For more details, see
+  /// \ref iteration_order "the documentation on iteration order".
   using code_block_iterator = boost::transform_iterator<
       BlockToNode<CodeBlock>,
       boost::filter_iterator<BlockKindEquals<Node::Kind::CodeBlock>,
                              BlockSet::index<by_offset>::type::iterator>>;
   /// \brief Range of \ref CodeBlock objects.
   ///
-  /// Blocks are yielded in offset order, ascending.
+  /// Blocks are yielded in offset order, ascending. For more details, see
+  /// \ref iteration_order "the documentation on iteration order".
   using code_block_range = boost::iterator_range<code_block_iterator>;
   /// \brief Sub-range of code blocks overlapping an address or range of
   /// addreses.
   ///
-  /// Blocks are yielded in offset order, ascending.
+  /// Blocks are yielded in offset order, ascending. For more details, see
+  /// \ref iteration_order "the documentation on iteration order".
   using code_block_subrange = boost::iterator_range<boost::transform_iterator<
       BlockToNode<CodeBlock>,
       boost::filter_iterator<
           BlockKindEquals<Node::Kind::CodeBlock>,
           boost::indirect_iterator<BlockIntMap::codomain_type::iterator>>>>;
   /// \brief Const iterator over \ref CodeBlock objects.
   ///
-  /// Blocks are yielded in offset order, ascending.
+  /// Blocks are yielded in offset order, ascending. For more details, see
+  /// \ref iteration_order "the documentation on iteration order".
   using const_code_block_iterator = boost::transform_iterator<
       BlockToNode<const CodeBlock>,
       boost::filter_iterator<BlockKindEquals<Node::Kind::CodeBlock>,
                              BlockSet::index<by_offset>::type::const_iterator>>;
   /// \brief Const range of \ref CodeBlock objects.
   ///
-  /// Blocks are yielded in offset order, ascending.
+  /// Blocks are yielded in offset order, ascending. For more details, see
+  /// \ref iteration_order "the documentation on iteration order".
   using const_code_block_range =
       boost::iterator_range<const_code_block_iterator>;
   /// \brief Const sub-range of code blocks overlapping an address or range of
   /// addreses.
   ///
-  /// Blocks are yielded in offset order, ascending.
+  /// Blocks are yielded in offset order, ascending. For more details, see
+  /// \ref iteration_order "the documentation on iteration order".
   using const_code_block_subrange =
       boost::iterator_range<boost::transform_iterator<
           BlockToNode<const CodeBlock>,
@@ -828,40 +839,46 @@ class GTIRB_EXPORT_API ByteInterval : public Node {
 
   /// \brief Iterator over \ref DataBlock objects.
   ///
-  /// Blocks are yielded in offset order, ascending.
+  /// Blocks are yielded in offset order, ascending. For more details, see
+  /// \ref iteration_order "the documentation on iteration order".
   using data_block_iterator = boost::transform_iterator<
       BlockToNode<DataBlock>,
       boost::filter_iterator<BlockKindEquals<Node::Kind::DataBlock>,
                              BlockSet::index<by_offset>::type::iterator>>;
   /// \brief Range of \ref DataBlock objects.
   ///
-  /// Blocks are yielded in offset order, ascending.
+  /// Blocks are yielded in offset order, ascending. For more details, see
+  /// \ref iteration_order "the documentation on iteration order".
   using data_block_range = boost::iterator_range<data_block_iterator>;
   /// \brief Sub-range of data blocks overlapping an address or range of
   /// addreses.
   ///
-  /// Blocks are yielded in offset order, ascending.
+  /// Blocks are yielded in offset order, ascending. For more details, see
+  /// \ref iteration_order "the documentation on iteration order".
   using data_block_subrange = boost::iterator_range<boost::transform_iterator<
       BlockToNode<DataBlock>,
       boost::filter_iterator<
           BlockKindEquals<Node::Kind::DataBlock>,
           boost::indirect_iterator<BlockIntMap::codomain_type::iterator>>>>;
   /// \brief Const iterator over \ref DataBlock objects.
   ///
-  /// Blocks are yielded in offset order, ascending.
+  /// Blocks are yielded in offset order, ascending. For more details, see
+  /// \ref iteration_order "the documentation on iteration order".
   using const_data_block_iterator = boost::transform_iterator<
       BlockToNode<const DataBlock>,
       boost::filter_iterator<BlockKindEquals<Node::Kind::DataBlock>,
                              BlockSet::index<by_offset>::type::const_iterator>>;
   /// \brief Const range of \ref DataBlock objects.
   ///
-  /// Blocks are yielded in offset order, ascending.
+  /// Blocks are yielded in offset order, ascending. For more details, see
+  /// \ref iteration_order "the documentation on iteration order".
   using const_data_block_range =
       boost::iterator_range<const_data_block_iterator>;
   /// \brief Const sub-range of data blocks overlapping an address or range of
   /// addreses.
   ///
-  /// Blocks are yielded in offset order, ascending.
+  /// Blocks are yielded in offset order, ascending. For more details, see
+  /// \ref iteration_order "the documentation on iteration order".
   using const_data_block_subrange =
       boost::iterator_range<boost::transform_iterator<
           BlockToNode<const DataBlock>,

include/gtirb/DecodeMode.hpp

@@ -1,4 +1,4 @@
-//===- CodeBlock.hpp ---------------------------------------------*- C++-*-===//
+//===- DecodeMode.hpp --------------------------------------------*- C++-*-===//
 //
 //  Copyright (C) 2024 GrammaTech, Inc.
 //

include/gtirb/IR.hpp

@@ -777,30 +777,36 @@ class GTIRB_EXPORT_API IR : public AuxDataContainer {
 
   /// \brief Iterator over blocks.
   ///
-  /// Blocks are yielded in address order, ascending.
+  /// Blocks are yielded in address order, ascending. For more details, see
+  /// \ref iteration_order "the documentation on iteration order".
   using block_iterator =
       MergeSortedIterator<Module::block_iterator, BlockAddressLess>;
   /// \brief Range of blocks.
   ///
-  /// Blocks are yielded in address order, ascending.
+  /// Blocks are yielded in address order, ascending. For more details, see
+  /// \ref iteration_order "the documentation on iteration order".
   using block_range = boost::iterator_range<block_iterator>;
   /// \brief Sub-range of blocks overlapping an address or range of addreses.
   ///
-  /// Blocks are yielded in address order, ascending.
+  /// Blocks are yielded in address order, ascending. For more details, see
+  /// \ref iteration_order "the documentation on iteration order".
   using block_subrange = boost::iterator_range<
       MergeSortedIterator<Module::block_subrange::iterator, BlockAddressLess>>;
   /// \brief Iterator over blocks.
   ///
-  /// Blocks are yielded in address order, ascending.
+  /// Blocks are yielded in address order, ascending. For more details, see
+  /// \ref iteration_order "the documentation on iteration order".
   using const_block_iterator =
       MergeSortedIterator<Module::const_block_iterator, BlockAddressLess>;
   /// \brief Range of blocks.
   ///
-  /// Blocks are yielded in address order, ascending.
+  /// Blocks are yielded in address order, ascending. For more details, see
+  /// \ref iteration_order "the documentation on iteration order".
   using const_block_range = boost::iterator_range<const_block_iterator>;
   /// \brief Sub-range of blocks overlapping an address or range of addreses.
   ///
-  /// Blocks are yielded in address order, ascending.
+  /// Blocks are yielded in address order, ascending. For more details, see
+  /// \ref iteration_order "the documentation on iteration order".
   using const_block_subrange = boost::iterator_range<MergeSortedIterator<
       Module::const_block_subrange::iterator, BlockAddressLess>>;
 
@@ -946,27 +952,32 @@ class GTIRB_EXPORT_API IR : public AuxDataContainer {
 
   /// \brief Iterator over \ref CodeBlock objects.
   ///
-  /// Blocks are yielded in address order, ascending.
+  /// Blocks are yielded in address order, ascending. For more details, see
+  /// \ref iteration_order "the documentation on iteration order".
   using code_block_iterator =
       MergeSortedIterator<Module::code_block_iterator, AddressLess>;
   /// \brief Range of \ref CodeBlock objects.
   ///
-  /// Blocks are yielded in address order, ascending.
+  /// Blocks are yielded in address order, ascending. For more details, see
+  /// \ref iteration_order "the documentation on iteration order".
   using code_block_range = boost::iterator_range<code_block_iterator>;
   /// \brief Sub-range of \ref CodeBlock objects overlapping an address or range
   /// of addreses.
   ///
-  /// Blocks are yielded in address order, ascending.
+  /// Blocks are yielded in address order, ascending. For more details, see
+  /// \ref iteration_order "the documentation on iteration order".
   using code_block_subrange = boost::iterator_range<
       MergeSortedIterator<Module::code_block_subrange::iterator, AddressLess>>;
   /// \brief Iterator over \ref CodeBlock objects.
   ///
-  /// Blocks are yielded in address order, ascending.
+  /// Blocks are yielded in address order, ascending. For more details, see
+  /// \ref iteration_order "the documentation on iteration order".
   using const_code_block_iterator =
       MergeSortedIterator<Module::const_code_block_iterator, AddressLess>;
   /// \brief Range of \ref CodeBlock objects.
   ///
-  /// Blocks are yielded in address order, ascending.
+  /// Blocks are yielded in address order, ascending. For more details, see
+  /// \ref iteration_order "the documentation on iteration order".
   using const_code_block_range =
       boost::iterator_range<const_code_block_iterator>;
   /// \brief Sub-range of \ref CodeBlock objects overlapping an address or range
@@ -1118,22 +1129,26 @@ class GTIRB_EXPORT_API IR : public AuxDataContainer {
 
   /// \brief Iterator over \ref DataBlock objects.
   ///
-  /// Blocks are yielded in address order, ascending.
+  /// Blocks are yielded in address order, ascending. For more details, see
+  /// \ref iteration_order "the documentation on iteration order".
   using data_block_iterator =
       MergeSortedIterator<Module::data_block_iterator, AddressLess>;
   /// \brief Range of \ref DataBlock objects.
   ///
-  /// Blocks are yielded in address order, ascending.
+  /// Blocks are yielded in address order, ascending. For more details, see
+  /// \ref iteration_order "the documentation on iteration order".
   using data_block_range = boost::iterator_range<data_block_iterator>;
   /// \brief Sub-range of \ref DataBlock objects overlapping an address or range
   /// of addreses.
   ///
-  /// Blocks are yielded in address order, ascending.
+  /// Blocks are yielded in address order, ascending. For more details, see
+  /// \ref iteration_order "the documentation on iteration order".
   using data_block_subrange = boost::iterator_range<
       MergeSortedIterator<Module::data_block_subrange::iterator, AddressLess>>;
   /// \brief Iterator over \ref DataBlock objects.
   ///
-  /// Blocks are yielded in address order, ascending.
+  /// Blocks are yielded in address order, ascending. For more details, see
+  /// \ref iteration_order "the documentation on iteration order".
   using const_data_block_iterator =
       MergeSortedIterator<Module::const_data_block_iterator, AddressLess>;
   /// \brief Range of \ref DataBlock objects.
@@ -1144,7 +1159,8 @@ class GTIRB_EXPORT_API IR : public AuxDataContainer {
   /// \brief Sub-range of \ref DataBlock objects overlapping an address or range
   /// of addreses.
   ///
-  /// Blocks are yielded in address order, ascending.
+  /// Blocks are yielded in address order, ascending. For more details, see
+  /// \ref iteration_order "the documentation on iteration order".
   using const_data_block_subrange = boost::iterator_range<MergeSortedIterator<
       Module::const_data_block_subrange::iterator, AddressLess>>;