From a6fb2d25d4451640c8b967aa213bcb476e85bf37 Mon Sep 17 00:00:00 2001 From: Denis Blank Date: Sat, 10 Mar 2018 08:38:40 +0100 Subject: [PATCH] First work on switching over to a new doxygen driven documentation --- doc/Doxyfile | 12 ++++---- doc/Index.md | 40 ------------------------- doc/index.dox | 81 +++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 87 insertions(+), 46 deletions(-) delete mode 100644 doc/Index.md create mode 100644 doc/index.dox diff --git a/doc/Doxyfile b/doc/Doxyfile index a798841..98e6034 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -790,8 +790,7 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = ../../include \ - ../Index.md +INPUT = ../include # 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 @@ -858,6 +857,7 @@ FILE_PATTERNS = *.c \ *.ucf \ *.qsf \ *.as \ + *.dox \ *.js # The RECURSIVE tag can be used to specify whether or not subdirectories should @@ -873,9 +873,9 @@ RECURSIVE = YES # Note that relative paths are relative to the directory from which doxygen is # run. -EXCLUDE = ../../dep \ - ../../test \ - ../../examples +EXCLUDE = ../dep \ + ../test \ + ../examples # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or # directories that are symbolic links (a Unix file system feature) are excluded @@ -984,7 +984,7 @@ FILTER_SOURCE_PATTERNS = # (index.html). This can be useful if you have a project on for instance GitHub # and want to reuse the introduction page also for the doxygen output. -USE_MDFILE_AS_MAINPAGE = Index.md +USE_MDFILE_AS_MAINPAGE = #--------------------------------------------------------------------------- # Configuration options related to source browsing diff --git a/doc/Index.md b/doc/Index.md deleted file mode 100644 index e8b64b8..0000000 --- a/doc/Index.md +++ /dev/null @@ -1,40 +0,0 @@ -![](https://raw.githubusercontent.com/Naios/continuable/master/doc/slideshow.gif) - -## Content - -- **Class cti::continuable_base** - for building up a continuation chain. - - \link cti::continuable_base::then then\endlink - adds a callback or cti::continuable_base to the invocation chain. - - \link cti::continuable_base::fail fail\endlink - adds an error callback to the invocation chain. - - \link cti::continuable_base::next next\endlink - adds an error and result callback to the invocation chain. - - \link cti::continuable_base::operator | operator|\endlink - connects another object through \link cti::continuable_base::then then\endlink. - - \link cti::continuable_base::operator && operator&&\endlink - connects another cti::continuable_base with an *all* logic. - - \link cti::continuable_base::operator|| operator||\endlink - connects another cti::continuable_base with an *any* logic. - - \link cti::continuable_base::operator>> operator>>\endlink - connects another cti::continuable_base with a *sequential* logic. - - \link cti::continuable_base::done done\endlink - \copybrief cti::continuable_base::done - - \link cti::continuable_base::freeze freeze \endlink - prevents the automatic invocation on destruction of the cti::continuable_base. - - \link cti::continuable_base::is_frozen is_frozen\endlink - \copybrief cti::continuable_base::is_frozen -- **Class cti::promise_base** - for resolving a continuation chain through a result or error. - - \link cti::promise_base::set_value set_value\endlink - resolves the continuation chain through a result. - - \link cti::promise_base::set_exception set_exception\endlink - resolves the continuation chain through an error. -- **Helper functions** - - \link cti::make_continuable make_continuable\endlink - creates a cti::continuable_base from a callback tanking function. - - \link cti::when_all when_all\endlink - connects all given cti::continuable_base objects with an *all* logic. - - \link cti::when_any when_any\endlink - connects all given cti::continuable_base objects with an *any* logic. - - \link cti::when_seq when_seq\endlink - connects all given cti::continuable_base objects with a *sequence* logic. -- **Transforms** - Apply a transform to the continuable - - \link cti::transforms::futurize futurize\endlink - \copybrief cti::transforms::futurize - - \link cti::transforms::flatten flatten\endlink - \copybrief cti::transforms::flatten -- **Predefined (erased) types** - Predefined type erarasures for continuables and promises - - \link cti::promise promise\endlink - \copybrief cti::promise - - \link cti::continuable continuable\endlink - \copybrief cti::continuable -- **Class cti::continuable_trait** - A trait class for defining your own cti::continuable_base trait with the type-erasure backend of your choice. - - \link cti::continuable_trait::promise promise\endlink - \copybrief cti::continuable_trait::promise - - \link cti::continuable_trait::continuable continuable\endlink - \copybrief cti::continuable_trait::continuable -- **GTest macros:** - - \link ASSERT_ASYNC_COMPLETION ASSERT_ASYNC_COMPLETION \endlink - \copybrief ASSERT_ASYNC_COMPLETION - - \link ASSERT_ASYNC_INCOMPLETION ASSERT_ASYNC_INCOMPLETION \endlink - \copybrief ASSERT_ASYNC_INCOMPLETION - - \link ASSERT_ASYNC_VALIDATION ASSERT_ASYNC_VALIDATION \endlink - \copybrief ASSERT_ASYNC_VALIDATION - - \link ASSERT_ASYNC_BINARY_VALIDATION ASSERT_ASYNC_BINARY_VALIDATION \endlink - \copybrief ASSERT_ASYNC_BINARY_VALIDATION - - \link EXPECT_ASYNC_RESULT EXPECT_ASYNC_RESULT \endlink - \copybrief EXPECT_ASYNC_RESULT - - \link ASSERT_ASYNC_RESULT ASSERT_ASYNC_RESULT \endlink - \copybrief ASSERT_ASYNC_RESULT - - \link ASSERT_ASYNC_TYPES ASSERT_ASYNC_TYPES \endlink - \copybrief ASSERT_ASYNC_TYPES diff --git a/doc/index.dox b/doc/index.dox new file mode 100644 index 0000000..dda5873 --- /dev/null +++ b/doc/index.dox @@ -0,0 +1,81 @@ +/* + Copyright(c) 2015 - 2018 Denis Blank + + Permission is hereby granted, free of charge, to any person obtaining a copy + of this software and associated documentation files(the "Software"), to deal + in the Software without restriction, including without limitation the rights + to use, copy, modify, merge, publish, distribute, sublicense, and / or sell + copies of the Software, and to permit persons to whom the Software is + furnished to do so, subject to the following conditions : + + The above copyright notice and this permission notice shall be included in + all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.IN NO EVENT SHALL THE + AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + SOFTWARE. +*/ + +namespace cti { +/** \mainpage Continuable + +\section mainpage-overview Overview + +Continuable is a C++14 library that provides full support for: + - lazy async continuation chaining based on **callbacks** (*then*) and expression templates, callbacks are wrapped nicely as promises. + - **no enforced type-erasure** which means we need less heap allocations than comparable libraries, strictly following the "don't pay for what you don't use" principle. + - support for **connections** between continuables through an **all, any or sequential** strategy through expressive operator overloads **&&**, || and >>. + - asynchronous **error handling** through exceptions, error coded or user defined types. + - **syntactic sugar** for instance: **partial invocation**, **tuple unpacking** and **executors**. + +\section mainpage-getting-started Getting started + +Continuable is a header-only library with zero compilation dependencies. +The \ref installation is explained in its own chapter. + +The \ref tutorial is everything you need in order to get to know the libraries +API. Beside of this there is a detailed in-source documentation provided. + +\section mainpage-contact Contributing and Questions + +Through the [Github issue tracker](https://github.com/Naios/continuable/issues) +you are welcomed to ask for questions, contribute code or request new features. +Also I would like to hear your personal opinion about the library design or +your personal experience in using the library to improve it. + +\note + If you like the library I would be glad if you star it on Github, + since this helps other users to find the library. + +\section mainpage-license License + +Continuable is licensed under the MIT license: + +> +> Copyright(c) 2015 - 2018 Denis Blank +> +> Permission is hereby granted, free of charge, to any person obtaining a copy +> of this software and associated documentation files(the "Software"), to deal +> in the Software without restriction, including without limitation the rights +> to use, copy, modify, merge, publish, distribute, sublicense, and / or sell +> copies of the Software, and to permit persons to whom the Software is +> furnished to do so, subject to the following conditions : +> +> The above copyright notice and this permission notice shall be included in +> all copies or substantial portions of the Software. +> +> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.IN NO EVENT SHALL THE +> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +> SOFTWARE. +> + +*/ +}