Merge pull request #372 from CrowCpp/doc_updates

Updated documentation in mkdocs and doxygen

Doxyfile

@@ -680,7 +680,7 @@ GENERATE_DEPRECATEDLIST= YES
 # sections, marked by \if <section_label> ... \endif and \cond <section_label>
 # ... \endcond blocks.
 
-ENABLED_SECTIONS       = $(RAPIDJSON_SECTIONS)
+ENABLED_SECTIONS       = 
 
 # The MAX_INITIALIZER_LINES tag determines the maximum number of lines that the
 # initial value of a variable or macro / define can have for it to appear in the
@@ -2129,14 +2129,7 @@ INCLUDE_FILE_PATTERNS  =
 # recursively expanded use the := operator instead of the = operator.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-PREDEFINED             = RAPIDJSON_DOXYGEN_RUNNING \
-                         "RAPIDJSON_NAMESPACE_BEGIN=namespace rapidjson {" \
-                         "RAPIDJSON_NAMESPACE_END=}" \
-                         RAPIDJSON_REMOVEFPTR_(x)=x \
-                         RAPIDJSON_ENABLEIF_RETURN(cond \
-                         "returntype)=RAPIDJSON_REMOVEFPTR_ returntype" \
-                         RAPIDJSON_DISABLEIF_RETURN(cond \
-                         "returntype)=RAPIDJSON_REMOVEFPTR_ returntype"
+PREDEFINED             = 
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The
@@ -2145,7 +2138,7 @@ PREDEFINED             = RAPIDJSON_DOXYGEN_RUNNING \
 # definition found in the source code.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-EXPAND_AS_DEFINED      = RAPIDJSON_NOEXCEPT
+EXPAND_AS_DEFINED      = 
 
 # If the SKIP_FUNCTION_MACROS tag is set to YES then doxygen's preprocessor will
 # remove all references to function-like macros that are alone on a line, have

docs/getting_started/setup/legacy.md

@@ -1,4 +1,4 @@
-This page explains how to set Crow up for use with your project (***For versions 0.3+2 and lower***).
+This page explains how to set Crow up for use with your project (***For versions 0.3+4 and lower***).
 
 
 ##Requirements
@@ -34,7 +34,7 @@ Use your package manager to install the following:
 Microsoft Visual Studio 2019 (older versions not tested)
 
 ##Downloading
-Either run `git clone https://github.com/crowcpp/crow.git` or download `crow_all.h` from the releases section. You can also download a zip of the project on github.
+Either run `git clone https://github.com/crowcpp/crow.git` or download `crow_all.h` from the releases section. You can also download a zip of the project on Github.
 
 ##Includes folder
 1. Copy the `/includes` folder to your project's root folder.
@@ -126,7 +126,7 @@ cd build
 cmake ..
 make
 ```
-Running Cmake will create `crow_all.h` file and place it in the build directory.<br>
+Running CMake will create `crow_all.h` file and place it in the build directory.<br>
 
 You can run tests with following command:
 ```

docs/getting_started/setup/linux.md

@@ -32,14 +32,20 @@ You can also download the `crow_all.h` file and simply include that into your pr
 <br><br>
 ### Installing from source
 #### Using CMake
-1. Download Crow's source code (Either through github's UI or by using<br> `git clone https://github.com/CrowCpp/Crow.git`).
+1. Download Crow's source code (Either through Github's UI or by using<br> `git clone https://github.com/CrowCpp/Crow.git`).
 2. Run `mkdir build` inside of crow's source directory.
 3. Navigate to the new "build" directory and run the following:<br>
 `cmake .. -DCROW_BUILD_EXAMPLES=OFF -DCROW_BUILD_TESTS=OFF`
 4. Run `make install`.
-!!!note
+
+!!! note
 
     You can ignore `-DCROW_BUILD_EXAMPLES=OFF -DCROW_BUILD_TESTS=OFF` if you want to build the Examples and Unit Tests.
+
+!!! note
+
+    You can uninstall Crow at a later time using `make uninstall`.
+
 <br>
 #### Manually
 Crow can be installed manually on your Linux computer.
@@ -53,13 +59,15 @@ Crow can be installed manually on your Linux computer.
     Copy Crow's `include` directory to the `/usr/local/include` directory.
 
 ##### Single header (crow_all.h)
-!!!warning
+!!! warning
 
     `crow_all.h` is recommended only for small, possibly single source file projects, and ideally should not be installed on your system.
+
 navigate to the `scripts` directory and run `./merge_all.py ../include crow_all.h`. This will generate a `crow_all.h` file that you can use in your projects.
-!!!note
+!!! note
 
     You can also include or exclude middlewares from your `crow_all.h` by using `-i` or `-e` followed by the middleware header file names separated by a comma (e.g. `merge_all.py ../include crow_all.h -e cookie_parser` to exclude the cookie parser middleware).
+
 ## Compiling your project
 ### Using CMake
 In order to get your CMake project to work with Crow, all you need are the following lines in your CMakeLists.txt:
@@ -74,6 +82,6 @@ All you need to do is run the following command:
 g++ main.cpp -lpthread
 ```
 You can use arguments like `-DCROW_ENABLE_DEBUG`, `-DCROW_ENABLE_COMPRESSION -lz` for HTTP Compression, or `-DCROW_ENABLE_SSL -lssl` for HTTPS support, or even replace g++ with clang++.
-!!!warning
+!!! warning
 
     If you're using a version of boost prior to 1.69, you'll need to add the argument `-lboost_system` in order for you Crow application to compile correctly.

docs/getting_started/setup/macos.md

@@ -16,7 +16,7 @@ You can generate your own single header file by navigating to the `scripts` fold
 python3 merge_all.py ../include crow_all.h
 ```
 This will generate a `crow_all.h` file which you can use in the following steps
-!!!warning
+!!! warning
 
     `crow_all.h` is recommended only for small, possibly single source file projects. For larger projects, it is advised to use the multi-header version.
 
@@ -44,7 +44,7 @@ This will generate a `crow_all.h` file which you can use in the following steps
 
 
 ## Building Crow's tests/examples
-!!!note
+!!! note
 
     This tutorial can be used for Crow projects built with CMake as well
 
@@ -56,20 +56,20 @@ This will generate a `crow_all.h` file which you can use in the following steps
     2. `cd build`
     3. `cmake ..`
     4. `make -j12`
-!!!note
+!!! note
 
-        You can add options like `-DCROW_ENABLE_SSL`, `-DCROW_ENABLE_COMPRESSION`, or `-DCROW_AMALGAMATE` to `3.c` to build their tests/examples.
+        You can add options like `-DCROW_ENABLE_SSL`, `-DCROW_ENABLE_COMPRESSION`, or `-DCROW_AMALGAMATE` to `cmake ..` to build their tests/examples.
 
 ## Compiling using a compiler directly
 All you need to do is run the following command:
 ```
 g++ main.cpp -lpthread
 ```
-!!!note
+!!! note
 
-    You'll need to install GCC via `brew install gcc`. the Clang compiler should be part of Xcode or Xcode command line tools.
+    You'll need to install GCC via `brew install gcc`. the Clang compiler should be part of XCode or XCode command line tools.
 
 You can use arguments like `-DCROW_ENABLE_DEBUG`, `-DCROW_ENABLE_COMPRESSION -lz` for HTTP Compression, or `-DCROW_ENABLE_SSL -lssl` for HTTPS support, or even replace g++ with clang++.
-!!!warning
+!!! warning
 
     If you're using a version of boost prior to 1.69, you'll need to add the argument `-lboost_system` in order for you Crow application to compile correctly.

docs/guides/CORS.md

@@ -0,0 +1,7 @@
+Crow Allows a developer to set CORS policies by using the `CORSHandler` middleware.<br><br>
+
+This middleware can be added to the app simply by defining a `#!cpp crow::App<crow::CORSHandler>`. This will use the default CORS rules globally<br><br>
+
+The CORS rules can be modified by first getting the middleware via `#!cpp auto& cors = app.get_middleware<crow::CORSHandler>();`. The rules can be set per URL prefix using `prefix()`, per blueprint using `blueprint()`, or globally via `global()`. These will return a `CORSRules` object which contains the actual rules for the prefix, blueprint, or application. For more details go [here](../../reference/structcrow_1_1_c_o_r_s_handler.html).
+
+`CORSRules` can  be modified using the methods `origin()`, `methods()`, `headers()`, `max_age()`, `allow_credentials()`, or `ignore()`. For more details on these methods and what default values they take go [here](../../reference/structcrow_1_1_c_o_r_s_rules.html).

docs/guides/app.md

@@ -1,5 +1,5 @@
 A Crow app defines an interface to allow the developer access to all the different parts of the framework, without having to manually deal with each one.<br><br>
-An app allows access to the http server (for handling connections), router (for handling URLs and requests), Middlewares (for extending Crow), among many others.<br><br>
+An app allows access to the HTTP server (for handling connections), router (for handling URLs and requests), Middlewares (for extending Crow), among many others.<br><br>
 
 Crow has 2 different app types:
 
@@ -23,6 +23,11 @@ app.bindaddr(192.168.1.2)
 .multithreaded()
 .run();
 ```
+
+!!! note
+
+    The `run()` method is blocking. To run a Crow app asynchronously `run_async()` should be used instead.
+
 <br><br>
 
 For more info on middlewares, check out [this page](../middleware).<br><br>

docs/guides/auth.md

@@ -11,7 +11,7 @@ Every way boils down to the same basic flow:
 For the purposes of this tutorial, we will assume that the verification function is defined as `#!cpp bool verify(crow::request req, crow::response res)`
 
 ## Basic Auth
-Basic HTTP authentication requires the client to send the Username and Password as a single string, separated by a colon (':') and then encoded as base64. This data needs to be placed in the `Authorization` header of the request. A sample header using the credentials "Username" and "Password" would look like this: `Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=`.<br><br>
+Basic HTTP authentication requires the client to send the Username and Password as a single string, separated by a colon (':') and then encoded as Base64. This data needs to be placed in the `Authorization` header of the request. A sample header using the credentials "Username" and "Password" would look like this: `Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=`.<br><br>
 
 We don't need to worry about creating the request, we only need to extract the credentials from the `Authorization` header and verify them.
 !!! note
@@ -47,7 +47,7 @@ return true; //or false if the username/password are invalid
 Tokens are some form of unique data that a server can provide to a client in order to verify the client's identity later. While on the surface level they don't provide more security than a strong password, they are designed to be less valuable by being *temporary* and providing *limited access*. Variables like expiration time and access scopes are heavily reliant on the implementation however.<br><br>
 
 ### Access Tokens
-The kind of the token itself can vary depending on the implementation and project requirements: Many services use randomly generated strings as tokens. Then compare them against a database to retrieve the associated user data. Some services however prefer using data bearing tokens. One example of the latter kind is JWT, which uses JSON strings encoded in base64 and signed using a private key or an agreed upon secret. While this has the added hassle of signing the token to ensure that it's not been tampered with. It does allow for the client to issue tokens without ever needing to present a password or contact a server. The server would simply be able to verify the signature using the client's public key or secret.<br><br>
+The kind of the token itself can vary depending on the implementation and project requirements: Many services use randomly generated strings as tokens. Then compare them against a database to retrieve the associated user data. Some services however prefer using data bearing tokens. One example of the latter kind is JWT, which uses JSON strings encoded in Base64 and signed using a private key or an agreed upon secret. While this has the added hassle of signing the token to ensure that it's not been tampered with. It does allow for the client to issue tokens without ever needing to present a password or contact a server. The server would simply be able to verify the signature using the client's public key or secret.<br><br>
 
 ### Using an Access Token
 Authenticating with an access token usually involves 2 stages: The first being acquiring the access token from an authority (either by providing credentials such as a username and a password to a server or generating a signed token). The scope of the token (what kind of information it can read or change) is usually defined in this step.<br><br>

docs/guides/base64.md

@@ -0,0 +1,8 @@
+
+## Encoding
+Using `#!cpp crow::utility::base64encode(mystring, mystring.size())` will return a Base64 encoded string. For URL safe Base64 `#!cpp crow::utility::base64encode_urlsafe(mystring, mystring.size())` can be used. The key used in the encoding process can be changed, it is a string containing all 64 characters to be used.
+
+## Decoding
+**Introduced in: `master`**<br><br>
+
+Using `#!cpp crow::utility::base64decode(mystring, mystring.size())` with `mystring` being a Base64 encoded string will return a plain-text string. The function works with both normal and URL safe Base64. However it cannot decode a Base64 string encoded with a custom key.

docs/guides/blueprints.md

@@ -1,4 +1,4 @@
-!!!Warning
+!!! Warning
 
     This feature is currently only available on the "master" branch.
 
@@ -16,23 +16,23 @@ You can define routes in a blueprint, similarly to how `#!cpp CROW_ROUTE(app, "/
 ### Define a Prefix
 Blueprints can have a prefix assigned to them. This can be done when creating a new blueprint as in `#!cpp crow::blueprint bp("prefix");`. This prefix will be applied to all routes belonging to the blueprint, turning a route such as `/crow/rocks` into `/prefix/crow/rocks`.
 
-!!!Warning
+!!! Warning
 
     Unlike routes, blueprint prefixes should contain no slashes.
 
 
 ### Use a custom Static directory
 Blueprints let you define a custom static directory (relative to your working directory). This can be done by initializing a blueprint as `#!cpp crow::blueprint bp("prefix", "custom_static");`. This does not have an effect on `#!cpp set_static_file_info()`, it's only for when you want direct access to a file.
 
-!!!note
+!!! note
 
     Currently changing which endpoint the blueprint uses isn't possible, so whatever you've set in `CROW_STATIC_ENDPOINT` (default is "static") will be used. Making your final route `/prefix/static/filename`.
 
 
 ### Use a custom Templates directory
 Similar to static directories, You can set a custom templates directory (relative to your working directory). To do this you initialize the blueprint as `#!cpp crow::blueprint bp("prefix", "custom_static", "custom_templates");`. Any routes defined for the blueprint will use that directory when calling `#!cpp crow::mustache::load("filename.html")`.
 
-!!!note
+!!! note
 
     If you want to define a custom templates directory without defining a custom static directory, you can pass the static directory as an empty string. Making your constructor `#!cpp crow::blueprint bp("prefix", "", "custom_templates");`.
 

docs/guides/json.md

@@ -25,20 +25,26 @@ For more info on read values go [here](/reference/classcrow_1_1json_1_1rvalue.ht
 ## wvalue
 JSON write value, used for creating, editing and converting JSON to a string.<br><br>
 
-!!!note
+!!! note
 
     setting a `wvalue` to object type can be done by simply assigning a value to whatever string key you like, something like `#!cpp wval["key1"] = val1;`. Keep in mind that val1 can be any of the above types.
 
-A `wvalue` can be treated as an object or even a list (setting a value by using `json[3] = 32` for example). Please note that this will remove the data in the value if it isn't of List type.<br><br>
+A `wvalue` can be treated as an object or even a list (setting a value by using `json[3] = 32` for example). Please note that this will remove the data in the value if it isn't of List type.
 
-Additionally, a `wvalue` can be initialized as an object using an initializer list, an example object would be `wvalue x = {{"a", 1}, {"b", 2}}`. Or as a list using `wvalue x = json::wvalue::list({1, 2, 3})`, lists can include any type that `wvalue` supports.
+!!! warning
+
+    JSON does not allow floating point values like `NaN` or `INF`, Crow will output `null` instead of `NaN` or `INF` when converting `wvalue` to a string. (`{"Key": NaN}` becomes `{"Key": null}`) (master and later)
+
+<br><br>
+
+Additionally, a `wvalue` can be initialized as an object using an initializer list, an example object would be `wvalue x = {{"a", 1}, {"b", 2}}`. Or as a list using `wvalue x = json::wvalue::list({1, 2, 3})`, lists can include any type that `wvalue` supports.<br><br>
 
 An object type `wvalue` uses `std::unordered_map` by default, if you want to have your returned `wvalue` key value pairs be sorted (using `std::map`) you can add `#!cpp #define CROW_JSON_USE_MAP` to the top of your program.<br><br>
 
 A JSON `wvalue` can be returned directly inside a route handler, this will cause the `content-type` header to automatically be set to `Application/json` and the JSON value will be converted to string and placed in the response body. For more information go to [Routes](../routes).<br><br>
 
 For more info on write values go [here](../../reference/classcrow_1_1json_1_1wvalue.html).
 
-!!!note
+!!! note
 
     Crow's json exceptions can be disabled by using the `#!cpp #define CROW_JSON_NO_ERROR_CHECK` macro. This should increase the program speed with the drawback of having unexpected behavious when used incorrectly (e.g. by attempting to parse an invalid json object).

docs/guides/logging.md

@@ -1,5 +1,9 @@
 Crow comes with a simple and easy to use logging system.<br><br>
 
+!!! note
+
+    Currently Crow's Logger is not linked to the Crow application, meaning if an executable has more than one Crow application they'll be sharing any variables or classes relating to Logging.
+
 ## Setting up logging level
 You can set up the level at which crow displays logs by using the app's `loglevel(crow::LogLevel)` method.<br><br>
 
@@ -22,7 +26,13 @@ To set a logLevel, just use `#!cpp app.loglevel(crow::LogLevel::Warning)`, This
 ## Writing a log
 Writing a log is as simple as `#!cpp CROW_LOG_<LOG LEVEL> << "Hello";` (replace&lt;LOG LEVEL&gt; with the actual level in all caps, so you have `CROW_LOG_WARNING`).
 
+!!! note
+
+    Log times are reported in GMT timezone by default. This is because HTTP requires all reported times for requests and responses to be in GMT. This can be changed by using the macro `CROW_USE_LOCALTIMEZONE` which will set **only the log timezone** to the server's local timezone.
+
 ## Creating A custom logger
+**Introduced in: `master`**<br><br>
+
 Assuming you have an existing logger or Crow's default format just doesn't work for you. Crow allows you to use a custom logger for any log made using the `CROW_LOG_<LOG LEVEL>` macro.<br>
 All you need is a class extending `#!cpp crow::ILogHandler` containing the method `#!cpp void log(std::string, crow::LogLevel)`.<br>
 Once you have your custom logger, you need to set it via `#!cpp crow::logger::setHandler(&MyLogger);`. Here's a full example:<br>