Merge remote-tracking branch 'upstream/master' into new_api

2 files changed, 61 insertions, 7 deletions

diff --git a/other/apidsl/README.md b/other/apidsl/README.md
index 0b3e776d..3c194df5 100644
--- a/other/apidsl/README.md
+++ b/other/apidsl/README.md
@@ -1,11 +1,49 @@
-This folder contains the input file that can be used to generate the tox.h api 
-with: https://github.com/iphydf/apidsl
+This folder contains the input file (``tox.in.h``) that has to be used to generate the ``tox.h`` api with: https://github.com/iphydf/apidsl
 
-You can also use the following command if you can't install it:
+# Minimal requirements
 
+There are some minimal requirements to contribute to ``tox.h``:
+* unix environment
+* ``astyle`` ``>=2.03``
+* [``apidsl``](https://github.com/iphydf/apidsl) (you can use provided service with curl instead)
+
+## Quick way
+
+If you want to do it quickly and you don't have time for anything other than copypasting commands, you should have ``curl`` installed.
+
+
+1. Make sure that you have ``curl`` and ``>=astyle-2.03`` installed
+2. Modify [``tox.in.h``](/other/apidsl/tox.in.h)
+3. Run command below ↓
+
+Command to run from ``toxcore`` directory (quick way, involves using curl):
+```bash
+rm toxcore/tox.h && \
+( curl -X POST --data-binary @- https://criticism.herokuapp.com/apidsl < ./other/apidsl/tox.in.h > ./toxcore/tox.h ) && \
+astyle --options=./other/astyle/astylerc ./toxcore/tox.h
+```
+
+When formatting will be complete, you should see output like:
 ```
-curl -X POST --data-binary @- https://criticism.herokuapp.com/apidsl < tox.in.h > tox.h
+Formatted  ./toxcore/tox.h
+```
+
+You may want to make sure with ``git diff`` that changes made in ``tox.h`` reflect changes in ``tox.in.h``.
+
+And you're done.
+
+
+## Manually
+
+If you prefer to have more control over what is happening, there are steps below:
+
+1. Install [``apidsl``](https://github.com/iphydf/apidsl)
+2. Install ``astyle``, version 2.03 or later.
+3. Modify [``tox.in.h``](/other/apidsl/tox.in.h)
+4. Use ``apidsl`` ``??``
+5. Parse generated ``tox.h`` with astyle, minimal command for it would be:
+```bash
+astyle --options=./other/astyle/astylerc ./toxcore/tox.h
 ```
 
-Note that the output must be passed through astyle with the config in 
-other/astyle/astylerc to generate the exact same file.
+**Always pass output from ``apidsl`` through astyle.**
\ No newline at end of file
diff --git a/other/apidsl/tox.in.h b/other/apidsl/tox.in.h
index 30c78e44..4a0ab950 100644
--- a/other/apidsl/tox.in.h
+++ b/other/apidsl/tox.in.h
@@ -34,6 +34,14 @@ extern "C" {
 #endif
 %}
 
+
+/*****************************************************************************
+ * `tox.h` SHOULD *NOT* BE EDITED MANUALLY – any changes should be made to   *
+ * `tox.in.h`, located in `other/apidsl/`. For instructions on how to        *
+ * generate `tox.h` from `tox.in.h` please refer to `other/apidsl/README.md` *
+ *****************************************************************************/
+
+
 /** \page core Public core API for Tox clients.
  *
  * Every function that can fail takes a function-specific error code pointer
@@ -431,7 +439,15 @@ static class options {
     uint16_t end_port;
 
     /**
-     * The port to use for the TCP server. If 0, the tcp server is disabled.
+     * The port to use for the TCP server (relay). If 0, the TCP server is
+     * disabled.
+     *
+     * Enabling it is not required for Tox to function properly.
+     *
+     * When enabled, your Tox instance can act as a TCP relay for other Tox
+     * instance. This leads to increased traffic, thus when writing a client
+     * it is recommended to enable TCP server only if the user has an option
+     * to disable it.
      */
     uint16_t tcp_port;