From d6a2a3f07c9e20337d58538278759edda5785f69 Mon Sep 17 00:00:00 2001 From: q66 Date: Wed, 3 May 2017 02:14:27 +0200 Subject: [PATCH] include all examples in generated docs --- doc/Doxyfile | 6 +++--- examples/concurrency.cc | 6 ++++++ examples/coroutine1.cc | 5 +++++ examples/coroutine2.cc | 5 +++++ examples/format.cc | 6 ++++++ examples/listdir.cc | 5 +++++ examples/range.cc | 5 +++++ examples/range_pipe.cc | 5 +++++ examples/stream1.cc | 6 ++++++ examples/stream2.cc | 6 ++++++ ostd/concurrency.hh | 12 +++--------- ostd/coroutine.hh | 8 ++++++++ ostd/filesystem.hh | 2 ++ ostd/format.hh | 2 ++ ostd/io.hh | 8 ++++++++ ostd/range.hh | 16 ++++++++++++++++ ostd/stream.hh | 15 +++++---------- ostd/string.hh | 4 ++++ 18 files changed, 100 insertions(+), 22 deletions(-) diff --git a/doc/Doxyfile b/doc/Doxyfile index 77c3fde..58cdbf4 100644 --- a/doc/Doxyfile +++ b/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 diff --git a/examples/concurrency.cc b/examples/concurrency.cc index 10cf56d..9730ecf 100644 --- a/examples/concurrency.cc +++ b/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 #include diff --git a/examples/coroutine1.cc b/examples/coroutine1.cc index ba4cb5f..4756ff3 100644 --- a/examples/coroutine1.cc +++ b/examples/coroutine1.cc @@ -1,3 +1,8 @@ +/** @example coroutine1.cc + * + * An example of using plain coroutines as resumable functions. + */ + #include #include diff --git a/examples/coroutine2.cc b/examples/coroutine2.cc index d1e432d..956f642 100644 --- a/examples/coroutine2.cc +++ b/examples/coroutine2.cc @@ -1,3 +1,8 @@ +/** @example coroutine2.cc + * + * An example of using coroutines as generators as well as nested resume/yield. + */ + #include #include diff --git a/examples/format.cc b/examples/format.cc index 8f31f10..bf47602 100644 --- a/examples/format.cc +++ b/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 #include #include diff --git a/examples/listdir.cc b/examples/listdir.cc index 402bf6c..49410d8 100644 --- a/examples/listdir.cc +++ b/examples/listdir.cc @@ -1,3 +1,8 @@ +/** @example listdir.cc + * + * A simple example of integration of std::filesystem with ranges. + */ + #include #include #include diff --git a/examples/range.cc b/examples/range.cc index 73f90ab..dc0494f 100644 --- a/examples/range.cc +++ b/examples/range.cc @@ -1,3 +1,8 @@ +/** @exmaple range.cc + * + * Simple examples of usage of the range system without using the pipe syntax. + */ + #include #include diff --git a/examples/range_pipe.cc b/examples/range_pipe.cc index 9f175e1..fc14178 100644 --- a/examples/range_pipe.cc +++ b/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 #include diff --git a/examples/stream1.cc b/examples/stream1.cc index 1374ea6..4369d5b 100644 --- a/examples/stream1.cc +++ b/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 #include diff --git a/examples/stream2.cc b/examples/stream2.cc index 0aa66c1..af80787 100644 --- a/examples/stream2.cc +++ b/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 #include diff --git a/ostd/concurrency.hh b/ostd/concurrency.hh index 44d00b4..33f9f67 100644 --- a/ostd/concurrency.hh +++ b/ostd/concurrency.hh @@ -15,15 +15,7 @@ * * Typical usage of the concurrency system is as follows: * - * ~~~{.cc} - * #include - * - * int main() { - * ostd::coroutine_scheduler{}.start([]() { - * // the rest of main follows - * }); - * } - * ~~~ + * @include concurrency.cc * * 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. */ diff --git a/ostd/coroutine.hh b/ostd/coroutine.hh index 02c336d..2f72c55 100644 --- a/ostd/coroutine.hh +++ b/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. */ diff --git a/ostd/filesystem.hh b/ostd/filesystem.hh index b3148f5..4f292d7 100644 --- a/ostd/filesystem.hh +++ b/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. */ diff --git a/ostd/format.hh b/ostd/format.hh index 832abd3..235be2a 100644 --- a/ostd/format.hh +++ b/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. */ diff --git a/ostd/io.hh b/ostd/io.hh index c413ab8..68c350b 100644 --- a/ostd/io.hh +++ b/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. */ diff --git a/ostd/range.hh b/ostd/range.hh index c82a6ad..5ecae46 100644 --- a/ostd/range.hh +++ b/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. */ diff --git a/ostd/stream.hh b/ostd/stream.hh index eaae42c..e509c89 100644 --- a/ostd/stream.hh +++ b/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 + * @include stream2.cc * - * int main() { - * ostd::file_stream fs{"input.txt"}; - * for (auto const &line: fs.iter_lines()) { - * writefln("read line: %s", line); - * } - * } - * ~~~ + * And binary examples: + * + * @include stream1.cc * * See the examples provided with the library for further information. * diff --git a/ostd/string.hh b/ostd/string.hh index 6ae1ee5..689788d 100644 --- a/ostd/string.hh +++ b/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. * * @{