updating docs - WIP
diff --git a/README.md b/README.md
index 7fa1174..3a2637a 100644
--- a/README.md
+++ b/README.md
@@ -10,21 +10,23 @@
Note how a standard C++ operator for equality comparison is used - **doctest** has one core [**assertion macro**](doc/markdown/assertions.md) (it also has for *less than*, *equals*, *greater than*...) - yet the full expression is decomposed and the left and right values are logged.
-It is modeled after [**Catch**](https://github.com/philsquared/Catch) which is currently the most popular and easy to use alternative for testing in C++
+It is modeled after [**Catch**](https://github.com/philsquared/Catch) which is currently the most popular alternative for testing in C++ - check out [**the differences**](doc/markdown/faq.md).
---------
There are many C++ testing frameworks - [Catch](https://github.com/philsquared/Catch), [Boost.Test](http://www.boost.org/doc/libs/1_60_0/libs/test/doc/html/index.html), [UnitTest++](https://github.com/unittest-cpp/unittest-cpp), [cpputest](https://github.com/cpputest/cpputest), [googletest](https://github.com/google/googletest) and many [other](https://en.wikipedia.org/wiki/List_of_unit_testing_frameworks#C.2B.2B).
-What makes **doctest** different is that it is ultra light on compile times (by [**orders of magnitude**](doc/markdown/benchmarks.md)) and is unintrusive.
+What makes **doctest** different is that it is ultra light on compile times (by [**orders of magnitude**](doc/markdown/benchmarks.md#cost-of-including-the-header)) and is unintrusive.
The **key** differences between it and other testing libraries are:
-- Ultra light - [**below 10ms**](doc/markdown/benchmarks.md) of compile time overhead for including the header in a source file
+- Ultra light - [**below 10ms**](doc/markdown/benchmarks.md#cost-of-including-the-header) of compile time overhead for including the header in a source file
+- The [**fastest possible**](doc/markdown/benchmarks.md#cost-of-an-assertion-macro) assertion macros - 50k asserts can compile for under 30 seconds (even under 10 sec)
+- [**Subcases**](doc/markdown/tutorial.md#test-cases-and-subcases) - an intuitive way to share common setup and teardown code for test cases
- Offers a way to remove **everything** testing-related from the binary with the [**```DOCTEST_CONFIG_DISABLE```**](doc/markdown/configuration.md) identifier
- Doesn't pollute the global namespace (everything is in the ```doctest``` namespace) and doesn't drag **any** headers with it
- Doesn't produce any warnings even on the [**most aggressive**](scripts/common.cmake#L71) warning levels for **MSVC**/**GCC**/**Clang**
-- Very [**portable and well tested**](doc/markdown/features.md#extremely-portable) C++98 - per commit tested on CI with over 200 different builds (valgrind, sanitizers...)
-- Just one header and no external dependencies apart from the C/C++ standard library! (well... same as [**Catch**](https://github.com/philsquared/Catch)...)
+- Very [**portable and well tested**](doc/markdown/features.md#extremely-portable) C++98 - per commit tested on CI with over 220 different builds (valgrind, sanitizers...)
+- Just one header and no external dependencies apart from the C/C++ standard library
This allows the library to be used in more ways than any other - tests can be written directly in the production code!
@@ -65,14 +67,14 @@
-------------
- [Features and design goals](doc/markdown/features.md) - the complete list of features
-- [Roadmap](doc/markdown/roadmap.md#roadmap) - upcoming features
-- [Tutorial](doc/markdown/tutorial.md#tutorial) - make sure you have read it before the other parts of the documentation
+- [Roadmap](doc/markdown/roadmap.md) - upcoming features
- [Benchmarks](doc/markdown/benchmarks.md) - compile-time supremacy
- [Contributing](doc/markdown/contributing.md)
- [Examples](examples)
-------------
+- [Tutorial](doc/markdown/tutorial.md) - make sure you have read it before the other parts of the documentation
- [Assertion macros](doc/markdown/assertions.md)
- [Test cases, subcases and test fixtures](doc/markdown/testcases.md)
- [Command line](doc/markdown/commandline.md)
@@ -84,15 +86,17 @@
Sponsors
--------
-###Gold sponsors ( >= 100$ )
+### Rockstar sponsors ( >= 1000$ )
+
+### Gold sponsors ( >= 100$ )
- Pascal Thomet
-###Silver sponsors ( >= 20$ )
+### Silver sponsors ( >= 20$ )
- Manuel Freiberger
-###Bronze sponsors ( >= 5$ )
+### Bronze sponsors ( >= 5$ )
- Zahari Karadzhov
- Sébastien Feldis
diff --git a/doc/markdown/benchmarks.md b/doc/markdown/benchmarks.md
index 854ae83..1a96248 100644
--- a/doc/markdown/benchmarks.md
+++ b/doc/markdown/benchmarks.md
@@ -62,14 +62,12 @@
- instantiating the test runner in one source file costs ~1.5 seconds ```implement - baseline```
- the inclusion of ```doctest.h``` in one source file costs below 9ms ```(header_everywhere - implement) / 200```
-- including the library everywhere - but everything disabled - costs less than 2 seconds ```disabled - baseline```
+- including the library everywhere but everything disabled costs less than 2 seconds ```disabled - baseline``` for 200 files
#### [Catch](https://github.com/philsquared/Catch)
- instantiating the test runner in one source file costs ~5 second ```implement - baseline```
- (~12 seconds for MinGW-w64)
- the inclusion of ```catch.hpp``` in one source file costs around 430ms ```(header_everywhere - implement) / 200```
- (below 280ms for MinGW-w64 which is really odd)
----------
@@ -90,53 +88,43 @@
**doctest** specific:
-- **+disabled** - all test case and assert macros will be disabled with [**```DOCTEST_CONFIG_DISABLE```**](configuration.md)
- ```CHECK_EQ(a,b)``` - will use ```CHECK_EQ(a,b)``` instead of the expression decomposing ones
- ```CHECK_EQ_FAST(a,b)``` - will use ```FAST_CHECK_EQ(a,b)``` instead of the expression decomposing ones
- **+faster** - will add [**```DOCTEST_CONFIG_SUPER_FAST_ASSERTS```**](configuration.md) which speeds up ```FAST_CHECK_EQ(a,b)``` even more
+- **+disabled** - all test case and assert macros will be disabled with [**```DOCTEST_CONFIG_DISABLE```**](configuration.md)
-| doctest | baseline | ```CHECK(a==b)``` | +disabled | ```CHECK_EQ(a,b)``` | ```CHECK_EQ_FAST(a,b)``` | +faster |
-|---------------------|----------|-------------------|-----------|---------------------|--------------------------|---------|
-| MSVC Debug | 2.5 | 21 | 2.2 | 16.2 | 6.7 | 4.4 |
-| MSVC Release | 2.6 | 64 | 1.8 | 55 | 63 | 5.3 |
-| MinGW GCC Debug | 3.2 | 77 | 1.6 | 52 | 29.5 | 12.2 |
-| MinGW GCC Release | 3.9 | 425 | 1.9 | 295 | 81 | 18.6 |
-| Linux GCC Debug | 1.3 | 72 | 0.9 | 48 | 20.3 | 9.5 |
-| Linux GCC Release | 2.3 | 339 | 1.3 | 210 | 42 | 18.3 |
-| Linux Clang Debug | 1.3 | 70 | 0.9 | 46 | 18.8 | 7.0 |
-| Linux Clang Release | 1.8 | 205 | 1.1 | 136 | 30 | 10.8 |
+| doctest | baseline | ```CHECK(a==b)``` | ```CHECK_EQ(a,b)``` | ```CHECK_EQ_FAST(a,b)``` | +faster | +disabled |
+|---------------------|----------|-------------------|---------------------|--------------------------|---------|-----------|
+| MSVC Debug | 2.5 | 21 | 16.2 | 6.7 | 4.4 | 2.2 |
+| MSVC Release | 2.6 | 64 | 55 | 63 | 5.3 | 1.8 |
+| MinGW GCC Debug | 3.2 | 77 | 52 | 29.5 | 12.2 | 1.6 |
+| MinGW GCC Release | 3.9 | 425 | 295 | 81 | 18.6 | 1.9 |
+| Linux GCC Debug | 1.3 | 72 | 48 | 20.3 | 9.5 | 0.9 |
+| Linux GCC Release | 2.3 | 339 | 210 | 42 | 18.3 | 1.3 |
+| Linux Clang Debug | 1.3 | 70 | 46 | 18.8 | 7.0 | 0.9 |
+| Linux Clang Release | 1.8 | 205 | 136 | 30 | 10.8 | 1.1 |
-| Catch | baseline | ```CHECK(a==b)``` |
-|---------------------|----------|-------------------|
-| MSVC Debug | 8.4 | 34 |
-| MSVC Release | 9.7 | 77 |
-| MinGW GCC Debug | 20.5 | 115 |
-| MinGW GCC Release | 15.1 | 496 |
-| Linux GCC Debug | 7.3 | 101 |
-| Linux GCC Release | 10.3 | 435 |
-| Linux Clang Debug | 6.0 | 91 |
-| Linux Clang Release | 8.5 | 159 |
+And here are [**Catch**](https://github.com/philsquared/Catch) and **doctest 1.0** which only have normal ```CHECK(a==b)``` asserts:
-The following table is with normal ```CHECK(a==b)``` asserts using ```doctest 1.0``` (it didn't have any other) - released on 2016.05.22
-
-| doctest 1.0 | ```CHECK(a==b)``` |
-|---------------------|-------------------|
-| MSVC Debug | 58 |
-| MSVC Release | 367 |
-| MinGW GCC Debug | 202 |
-| MinGW GCC Release | 1257 |
-| Linux GCC Debug | 204 |
-| Linux GCC Release | 1090 |
-| Linux Clang Debug | 167 |
-| Linux Clang Release | 494 |
+| Catch | baseline | ```CHECK(a==b)``` | | doctest 1.0 | ```CHECK(a==b)``` |
+|---------------------|----------|-------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|---------------------|-------------------|
+| MSVC Debug | 8.4 | 34 | | MSVC Debug | 58 |
+| MSVC Release | 9.7 | 77 | | MSVC Release | 367 |
+| MinGW GCC Debug | 20.5 | 115 | | MinGW GCC Debug | 202 |
+| MinGW GCC Release | 15.1 | 496 | | MinGW GCC Release | 1257 |
+| Linux GCC Debug | 7.3 | 101 | | Linux GCC Debug | 204 |
+| Linux GCC Release | 10.3 | 435 | | Linux GCC Release | 1090 |
+| Linux Clang Debug | 6.0 | 91 | | Linux Clang Debug | 167 |
+| Linux Clang Release | 8.5 | 159 | | Linux Clang Release | 494 |
### Conclusion
**doctest 1.1**:
-- compared to 1.0 it improves the compile time of it's expression decomposing ```CHECK(a==b)``` macros by roughly 3 times - making it faster rather and not slower than [**Catch**](https://github.com/philsquared/Catch)
-- adds alternative macros of the form ```CHECK_EQ(a,b)``` with no expression decomposition - around 20% faster than ```CHECK(a==b)```
-- adds even faster asserts like ```FAST_CHECK_EQ(a,b)``` which don't have ```try/catch``` blocks - around 30-70% faster than ```CHECK_EQ(a,b)```
+- improves the compile time of it's ```CHECK(a==b)``` asserts by roughly 3 times compared to **doctest** 1.0 (released 2016.05.22)
+- is around 25% faster than [**Catch**](https://github.com/philsquared/Catch) when using expression decomposing ```CHECK(a==b)``` asserts
+- adds asserts of the form ```CHECK_EQ(a,b)``` with no expression decomposition - around 20% faster than ```CHECK(a==b)```
+- adds fast asserts like ```FAST_CHECK_EQ(a,b)``` with no ```try/catch``` blocks - around 30-70% faster than ```CHECK_EQ(a,b)```
- adds the [**```DOCTEST_CONFIG_SUPER_FAST_ASSERTS```**](configuration.md) identifier which makes the fast assertions even faster by another 35-80%
- using the [**```DOCTEST_CONFIG_DISABLE```**](configuration.md) identifier the assertions just disappear as if they were never written
diff --git a/doc/markdown/configuration.md b/doc/markdown/configuration.md
index cbbee62..7171284 100644
--- a/doc/markdown/configuration.md
+++ b/doc/markdown/configuration.md
@@ -1,35 +1,67 @@
## Configuration
-**doctest** is designed to "just work" as much as possible. It exposes a small set of defines for configuring how it is built.
+**doctest** is designed to "just work" as much as possible. It also allows configuring how it is built with a set of identifiers.
For most people the only configuration needed is telling **doctest** which source file should host all the implementation code:
-- **```DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN```**
+### **```DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN```**
- ```c++
+```c++
#define DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN
#include "doctest.h"
- ```
+```
- This should be done in only one source file! Otherwise there will be linker errors and slower build times.
+This should be done in only one source file! Otherwise there will be linker errors and slower build times.
-- **```DOCTEST_CONFIG_IMPLEMENT```** - if the client wants to [**supply the ```main()``` function**](main.md) (either to set an option with some value from the code or to integrate the framework into his existing project codebase) this define should be used.
+### **```DOCTEST_CONFIG_IMPLEMENT```**
-- **```DOCTEST_CONFIG_DISABLE```** - the next most important configuration option - when defined globally in the whole project before the inclusion of the framework header - everything testing - related is removed from the binary - including most of the framework implementation and every test case written anywhere! This is one of the most unique features of **doctest**.
+if the client wants to [**supply the ```main()``` function**](main.md) (either to set an option with some value from the code or to integrate the framework into his existing project codebase) this define should be used.
-- **```DOCTEST_CONFIG_NO_SHORT_MACRO_NAMES```** - this will remove all macros from **doctest** that don't have the **```DOCTEST_```** prefix - like **```CHECK```**, **```TEST_CASE```** and **```SUBCASE```**. Then only the full macro names will be available - **```DOCTEST_CHECK```**, **```DOCTEST_TEST_CASE```** and **```DOCTEST_SUBCASE```**. The user is free to make his own short versions of these macros - [**example**](../../examples/alternative_macros/)
+### **```DOCTEST_CONFIG_DISABLE```**
-- **```DOCTEST_CONFIG_NO_UNPREFIXED_OPTIONS```** - this will disable the short versions of the [**command line**](commandline.md) options and only the versions with ```-dt-``` prefix will be parsed by **doctest** - this is possible for easy interoperability with client command line option handling when the testing framework is integrated within a client codebase - so there are no clashes and so that the user can exclude everything starting with ```-dt-``` from their option parsing. This configuration option is relevant only for the source file where the library is implemented
+the next most important configuration option - when defined globally in the whole project before the inclusion of the framework header - everything testing - related is removed from the binary - including most of the framework implementation and every test case written anywhere! This is one of the most unique features of **doctest**.
-- **```DOCTEST_CONFIG_COLORS_NONE```** - this will remove support for colors in the console output of the framework. This configuration option is relevant only for the source file where the library is implemented
+### **```DOCTEST_CONFIG_NO_SHORT_MACRO_NAMES```**
-- **```DOCTEST_CONFIG_COLORS_WINDOWS```** - this will force the support for colors in the console output to use the Windows APIs and headers. This configuration option is relevant only for the source file where the library is implemented
+this will remove all macros from **doctest** that don't have the **```DOCTEST_```** prefix - like **```CHECK```**, **```TEST_CASE```** and **```SUBCASE```**. Then only the full macro names will be available - **```DOCTEST_CHECK```**, **```DOCTEST_TEST_CASE```** and **```DOCTEST_SUBCASE```**. The user is free to make his own short versions of these macros - [**example**](../../examples/alternative_macros/)
-- **```DOCTEST_CONFIG_COLORS_ANSI```** - this will force the support for colors in the console output to use ANSI escape codes. This configuration option is relevant only for the source file where the library is implemented
+### **```DOCTEST_CONFIG_NO_UNPREFIXED_OPTIONS```**
-- **```DOCTEST_CONFIG_USE_IOSFWD```** - the library by default provides a forward declaration of ```std::ostream``` in order to support the ```operator<<``` [**stringification**](stringification.md) mechanism. This is forbidden by the standard (even though it works everywhere on all tested compilers). However if the user wishes to be 100% standards compliant - then this configuration option can be used to force the inclusion of ```<iosfwd>```. It should be defined everywhere before the framework header is included.
+this will disable the short versions of the [**command line**](commandline.md) options and only the versions with ```-dt-``` prefix will be parsed by **doctest** - this is possible for easy interoperability with client command line option handling when the testing framework is integrated within a client codebase - so there are no clashes and so that the user can exclude everything starting with ```-dt-``` from their option parsing. This configuration option is relevant only for the source file where the library is implemented
-- **```DOCTEST_CONFIG_WITH_LONG_LONG```** - by default the library includes support for stringifying ```long long``` only if the value of ```__cplusplus``` is at least ```201103L``` (C++11) or if the compiler is MSVC 2003 or newer. Many compilers that don't fully support C++11 have it as an extension but it errors for GCC/Clang when the ```-std=c++98``` option is used and this cannot be detected with the preprocessor in any way. Use this configuration option if your compiler supports ```long long``` but doesn't yet support the full C++11 standard. It should be defined everywhere before the framework header is included.
+### **```DOCTEST_CONFIG_COLORS_NONE```**
+
+this will remove support for colors in the console output of the framework. This configuration option is relevant only for the source file where the library is implemented
+
+### **```DOCTEST_CONFIG_COLORS_WINDOWS```**
+
+this will force the support for colors in the console output to use the Windows APIs and headers. This configuration option is relevant only for the source file where the library is implemented
+
+### **```DOCTEST_CONFIG_COLORS_ANSI```**
+
+this will force the support for colors in the console output to use ANSI escape codes. This configuration option is relevant only for the source file where the library is implemented
+
+### **```DOCTEST_CONFIG_USE_IOSFWD```**
+
+the library by default provides a forward declaration of ```std::ostream``` in order to support the ```operator<<``` [**stringification**](stringification.md) mechanism. This is forbidden by the standard (even though it works everywhere on all tested compilers). However if the user wishes to be 100% standards compliant - then this configuration option can be used to force the inclusion of ```<iosfwd>```. It should be defined everywhere before the framework header is included.
+
+### **```DOCTEST_CONFIG_WITH_LONG_LONG```**
+
+by default the library includes support for stringifying ```long long``` only if the value of ```__cplusplus``` is at least ```201103L``` (C++11) or if the compiler is MSVC 2003 or newer. Many compilers that don't fully support C++11 have it as an extension but it errors for GCC/Clang when the ```-std=c++98``` option is used and this cannot be detected with the preprocessor in any way. Use this configuration option if your compiler supports ```long long``` but doesn't yet support the full C++11 standard. It should be defined everywhere before the framework header is included.
+
+DOCTEST_CONFIG_WITH_NULLPTR
+DOCTEST_CONFIG_WITH_LONG_LONG
+DOCTEST_CONFIG_WITH_STATIC_ASSERT
+
+DOCTEST_CONFIG_NO_NULLPTR
+DOCTEST_CONFIG_NO_LONG_LONG
+DOCTEST_CONFIG_NO_STATIC_ASSERT
+
+DOCTEST_CONFIG_ASSERTION_PARAMETERS_BY_VALUE
+DOCTEST_CONFIG_TREAT_CHAR_STAR_AS_STRING
+DOCTEST_CONFIG_NO_COMPARISON_WARNING_SUPPRESSION
+
+DOCTEST_CONFIG_SUPER_FAST_ASSERTS
---------------
diff --git a/doc/markdown/faq.md b/doc/markdown/faq.md
index aa20f22..bee578c 100644
--- a/doc/markdown/faq.md
+++ b/doc/markdown/faq.md
@@ -2,10 +2,28 @@
#TODO...
+- how is it different from Catch (or what is lacking)
+
+- require macros not working properly when using -fno-exceptions
+
+- static libraries - also mention https://github.com/pthom/doctest_registerlibrary
+
+- char* comparisons
+
+- how to get the most out of the library - fast asserts, custom macro names, etc.
+
+- how to write tests in header-only libraries (DOCTEST_LIBRARY_INCLUDED, and a tag)
+
- linker issues? Make sure you have instantiated the test runner in only one source file.
+- compiler errors in STL headers when including the doctest header
+
+ try using [**```DOCTEST_CONFIG_USE_IOSFWD```**](configuration.md#DOCTEST_CONFIG_USE_IOSFWD)
+
- stringification issues - if operator<<(ostream for a type is visible only in one source file...
+- why macros - aren't they evil? - http://accu.org/index.php/journals/2064
+
- why no regex and only wildcards
- tests are ran serially - no multi-threaded execution planned for now
@@ -24,6 +42,10 @@
- why c++98? because.
+- I'm a power user - is there anything else I should know?
+
+ separate headers
+
- will the library support checking for memory leaks? no. use tools like valgrind or the sanitizers.
- mixing different versions of the framework within the same executable?
diff --git a/doc/markdown/features.md b/doc/markdown/features.md
index 9b913f3..0eeab6c 100644
--- a/doc/markdown/features.md
+++ b/doc/markdown/features.md
@@ -5,7 +5,7 @@
## Unintrusive (transparent):
- everything testing-related can be removed from the binary executable by defining the [**```DOCTEST_CONFIG_DISABLE```**](configuration.md) identifier
-- very small and easy to integrate - single header - less than 3k LOC in the implementation translation unit and less than 1.5k LOC everywhere else - **extremely** low footprint on compile times - see the [**benchmarks**](benchmarks.md)
+- very small and easy to integrate - single header - **extremely** low footprint on compile times - see the [**benchmarks**](benchmarks.md)
- doesn't drag any headers when included (except for in the translation unit where the library gets implemented)
- everything is in the ```doctest``` namespace (and the implementation details are in a nested ```detail``` namespace)
- all macros have prefixes - some by default have unprefixed versions as well but that is optional - see [**configuration**](configuration.md)
diff --git a/doc/markdown/readme.md b/doc/markdown/readme.md
index 0b8b3dc..95dd795 100644
--- a/doc/markdown/readme.md
+++ b/doc/markdown/readme.md
@@ -3,13 +3,13 @@
- [Features and design goals](features.md) - the complete list of features
- [Roadmap](roadmap.md) - upcoming features
-- [Tutorial](tutorial.md) - make sure you have read it before the other parts of the documentation
- [Benchmarks](benchmarks.md) - compile time supremacy
- [Contributing](contributing.md)
- [Examples](../../examples)
-------------
+- [Tutorial](tutorial.md) - make sure you have read it before the other parts of the documentation
- [Assertion macros](assertions.md)
- [Test cases, subcases and test fixtures](testcases.md)
- [Command line](commandline.md)
diff --git a/scripts/random_dev_notes.md b/scripts/random_dev_notes.md
index c38551e..940b0f9 100644
--- a/scripts/random_dev_notes.md
+++ b/scripts/random_dev_notes.md
@@ -1,19 +1,3 @@
-- list the subcases as a major selling point on the main page - after the expression decomposition macro stuff
-- faq - why macros - http://accu.org/index.php/journals/2064
-- FAQ - how is it different from Catch (or what is lacking)
-- faq - require macros not working properly when using -fno-exceptions
-- FAQ - static libraries - also mention https://github.com/pthom/doctest_registerlibrary
-- faq - char* comparisons
-- default options should be mentioned (also clearFilters)
-- mention the new asserts
-- document the new config identifiers
-- for power users - separate headers
-- how to write tests in header-only libraries (DOCTEST_LIBRARY_INCLUDED, and a tag)
-- post the traffic screenshot in the FAQ - "how epic was the initial release"
-
-- a new page on how to get the most out of the library - fast asserts, custom macro names, etc.
-
-*the fastest possible assertion macros* in main readme
@@ -22,13 +6,22 @@
-- the project is in need of sponsors!
-cpp
-hackernews
-programming
-cplusplus
-isocpp.org
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+