include all examples in generated docs

doc/Doxyfile

@@ -790,7 +790,7 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = . ../ostd
+INPUT                  = . ../ostd ../examples
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -906,14 +906,14 @@ EXCLUDE_SYMBOLS        = detail
 # that contain example code fragments that are included (see the \include
 # command).
 
-EXAMPLE_PATH           =
+EXAMPLE_PATH           = ../examples
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the
 # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and
 # *.h) to filter out the source-files in the directories. If left blank all
 # files are included.
 
-EXAMPLE_PATTERNS       = *
+EXAMPLE_PATTERNS       = *.cc
 
 # If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be
 # searched for input files to be used with the \include or \dontinclude commands

examples/concurrency.cc

@@ -1,3 +1,9 @@
+/** @example concurrency.cc
+ *
+ * A simple example of the concurrency module usage, explaining schdulers,
+ * ostd::spawn(), ostd::tid as well as ostd::channel.
+ */
+
 #include <ostd/io.hh>
 #include <ostd/concurrency.hh>
 

examples/coroutine1.cc

@@ -1,3 +1,8 @@
+/** @example coroutine1.cc
+ *
+ * An example of using plain coroutines as resumable functions.
+ */
+
 #include <ostd/io.hh>
 #include <ostd/coroutine.hh>
 

examples/coroutine2.cc

@@ -1,3 +1,8 @@
+/** @example coroutine2.cc
+ *
+ * An example of using coroutines as generators as well as nested resume/yield.
+ */
+
 #include <ostd/io.hh>
 #include <ostd/coroutine.hh>
 

examples/format.cc

@@ -1,3 +1,9 @@
+/** @example format.cc
+ *
+ * An example of using the string formatting system, including various
+ * differences from C such as user defined type and range formatting.
+ */
+
 #include <unordered_map>
 #include <vector>
 #include <tuple>

examples/listdir.cc

@@ -1,3 +1,8 @@
+/** @example listdir.cc
+ *
+ * A simple example of integration of std::filesystem with ranges.
+ */
+
 #include <ostd/io.hh>
 #include <ostd/filesystem.hh>
 #include <ostd/range.hh>

examples/range.cc

@@ -1,3 +1,8 @@
+/** @exmaple range.cc
+ *
+ * Simple examples of usage of the range system without using the pipe syntax.
+ */
+
 #include <vector>
 
 #include <ostd/range.hh>

examples/range_pipe.cc

@@ -1,3 +1,8 @@
+/** @exmaple range_pipe.cc
+ *
+ * Simple examples of usage of the range system using the pipe syntax.
+ */
+
 #include <array>
 #include <ctime>
 

examples/stream1.cc

@@ -1,3 +1,9 @@
+/** @example stream1.cc
+ *
+ * An example of using streams to read and write binary files
+ * with some help from the standard range algorithms.
+ */
+
 #include <ostd/platform.hh>
 #include <ostd/io.hh>
 

examples/stream2.cc

@@ -1,3 +1,9 @@
+/** @example stream2.cc
+ *
+ * An example of using streams to process strings, including some
+ * standard range algorithm use.
+ */
+
 #include <vector>
 
 #include <ostd/algorithm.hh>

ostd/concurrency.hh

@@ -15,15 +15,7 @@
  *
  * Typical usage of the concurrency system is as follows:
  *
- * ~~~{.cc}
+ * @include concurrency.cc
- * #include <ostd/concurrency.hh>
- *
- * int main() {
- *     ostd::coroutine_scheduler{}.start([]() {
- *         // the rest of main follows
- *     });
- * }
- * ~~~
  *
  * See the examples provided with the library for further information.
  *
@@ -40,6 +32,8 @@
  * This file implements several schedulers as well as APIs to spawn
  * tasks, coroutines and channels that utilize the current scheduler's API.
  *
+ * @include concurrency.cc
+ *
  * @copyright See COPYING.md in the project tree for further information.
  */
 

ostd/coroutine.hh

@@ -14,6 +14,14 @@
  * also be used as generators and generally anywhere where you'd like to
  * suspend a function and resume it later (all kinds of async apps).
  *
+ * Plain coroutine usage:
+ *
+ * @include coroutine1.cc
+ *
+ * Generators and more:
+ *
+ * @include coroutine2.cc
+ *
  * @copyright See COPYING.md in the project tree for further information.
  */
 

ostd/filesystem.hh

@@ -14,6 +14,8 @@
  * It also provides range integration for directory iterators and
  * ostd::format_traits specialization for std::filesystem::path.
  *
+ * @include listdir.cc
+ *
  * @copyright See COPYING.md in the project tree for further information.
  */
 

ostd/format.hh

@@ -11,6 +11,8 @@
  * and supports custom object formatting without heap allocations as well
  * as formatting of ranges, tuples and more.
  *
+ * @include format.cc
+ *
  * @copyright See COPYING.md in the project tree for further information.
  */
 

ostd/io.hh

@@ -10,6 +10,14 @@
  * as well as wrappers over standard input/output/error and global functions
  * for formatted writing into standard output.
  *
+ * Some string examples:
+ *
+ * @include stream2.cc
+ *
+ * And binary examples:
+ *
+ * @include stream1.cc
+ *
  * @copyright See COPYING.md in the project tree for further information.
  */
 

ostd/range.hh

@@ -21,6 +21,14 @@
  * There is a whole article dedicated to ranges [here](@ref ranges). You can
  * also take a look at the many examples in the project tree.
  *
+ * Some more examples:
+ *
+ * @include range.cc
+ *
+ * Pipe syntax examples:
+ *
+ * @include range_pipe.cc
+ *
  * @{
  */
 
@@ -31,6 +39,14 @@
  * This file provides the actual range system implementation,
  * some basic range types, iteration utilities and range traits.
  *
+ * Some examples:
+ *
+ * @include range.cc
+ *
+ * Pipe syntax examples:
+ *
+ * @include range_pipe.cc
+ *
  * @copyright See COPYING.md in the project tree for further information.
  */
 

ostd/stream.hh

@@ -5,18 +5,13 @@
  * Libostd provides a custom stream system with considerably simpler API
  * and integration with other libostd features (such as ranges).
  *
- * A simple example:
+ * Some string examples:
  *
- * ~~~{.cc}
+ * @include stream2.cc
- * #include <ostd/io.hh>
  *
- * int main() {
+ * And binary examples:
- *     ostd::file_stream fs{"input.txt"};
+ *
- *     for (auto const &line: fs.iter_lines()) {
+ * @include stream1.cc
- *         writefln("read line: %s", line);
- *     }
- * }
- * ~~~
  *
  * See the examples provided with the library for further information.
  *

ostd/string.hh

@@ -27,6 +27,10 @@
  * }
  * ~~~
  *
+ * An example of using libostd string formatting:
+ *
+ * @include format.cc
+ *
  * See the examples provided with the library for further information.
  *
  * @{