Docs: Document language-specific callback constructs

3 files changed, 32 insertions, 5 deletions

diff --git a/docs/src/api/go/functions.md b/docs/src/api/go/functions.md
index 381f5be..fc4f0a1 100644
--- a/docs/src/api/go/functions.md
+++ b/docs/src/api/go/functions.md
@@ -8,7 +8,7 @@ func Register(name string, directory string, stateCallback func, debug bool) err
 - `directory`: The directory where the configs and logging should be stored
 - `stateCallback`: function with three arguments, full type:
   ```go
-  func(oldState string, newState string, data string)
+  func StateCallback(oldState string, newState string, data string)
   ```
 - `debug`: Whether or not we want to enable debugging
 
@@ -67,3 +67,10 @@ func Deregister() error
 ```
 
 Returns an `error`, can be nil indicating no error
+
+# Note on Callbacks
+Some functions (e.g. [the API for getting an OpenVPN/Wireguard config](http://localhost:3000/api/overview/getconfig.html)) need a (or multiple) callback(s) set. In Go, the callback function is given in the [Register function](#registering). The signature of this function is the following:
+```go
+func StateCallback(oldState string, newState string, data string)
+```
+Because certain callbacks need to be set, you can simply compare against `oldState` and `newState`. To show how this can be done in practice, we will give an example in the next section.
diff --git a/docs/src/api/overview/getconfig.md b/docs/src/api/overview/getconfig.md
index ca35835..65ca948 100644
--- a/docs/src/api/overview/getconfig.md
+++ b/docs/src/api/overview/getconfig.md
@@ -16,15 +16,15 @@ Used to obtain the OpenVPN/Wireguard config
 To get a configuration that is used to actually establish a tunnel with the VPN server, we have the Get Config function for Institute Access and Secure Internet (the exact name depends on the language you're using) function in the library. This function has two parameters *URL* and *Force TCP*.
 
 *URL* is the base url of the server to connect to
-e.g. `nl.eduvpn.org`. Use the correct function to indicate if it is an Institute Access server or a Secure Internet server. A user configured server is often an Institute Access server.
+e.g. `nl.eduvpn.org`. Use the correct function to indicate if it is an Institute Access server or a Secure Internet server. A user configured server is often an Institute Access server. In case of a Secure Internet server and no Secure Internet was configured previously, this URL is set as the home server. This means that this server is set as the authorization server for all secure internet servers.
 
-The *Force TCP* flag is a boolean that indicates whether or not we want to use TCP to connect over the VPN. This flag is useful if the user has enabled e.g. a setting that forces the use of TCP, which is only supported by OpenVPN. If the Force TCP flag is set to true but the server only supports Wireguard then an error is returned and the config will be empty.
+The *Force TCP* flag is a boolean that indicates whether or not we want to use TCP to connect over the VPN. This flag is useful if the user has enabled e.g. a setting that forces the use of TCP, which is only supported by OpenVPN. If the Force TCP flag is set to `true` but the server only supports Wireguard then an error is returned and the config will be empty.
 
 This function takes care of OAuth which has certain callbacks with data. Additionally, there are also callbacks that need to be registered for selecting the right profile to connect to. These callbacks will be explained now.
 
 The data that this function returns is the OpenVPN/Wireguard config as a string, the type of config (a string: "wireguard" or "openvpn") and an error if present.
 
-### Callback: OAuth started
+### Callback: OAuth started (OAuth_Started)
 
 OAuth has an important callback which is used to obtain the authorization URL by the client. This client needs to open this authorization URL in a web browser such that the user can authenticate with the VPN portal and then authorize the client to obtain OpenVPN/Wireguard configs.
 
@@ -36,7 +36,7 @@ The format of the authorization URL is e.g. this:
 
 This callback can be cancelled by using a `Cancel OAuth` function.
 
-### Callback: Selecting a profile
+### Callback: Selecting a profile (Ask_Profile)
 
 Another aspect that needs to be taken into account is the fact that there can be multiple profiles that a client can connect to. When the function gets called for obtaining an OpenVPN/Wireguard configuration, it asks the client which profile it wants to connect to using the callback that gets triggered on the Ask Profile state. The data is the list of profiles in JSON format, e.g.
 
diff --git a/docs/src/api/python/functions.md b/docs/src/api/python/functions.md
index 2a348cd..1d9aef5 100644
--- a/docs/src/api/python/functions.md
+++ b/docs/src/api/python/functions.md
@@ -79,3 +79,23 @@ def deregister() -> None
 ```
 
 Returns nothing. Raises an exception in case of an error.
+
+# Note on Callbacks
+Some functions (e.g. [the API for getting an OpenVPN/Wireguard config](http://localhost:3000/api/overview/getconfig.html)) need a (or multiple) callbacks set. In Python, the callback function is set using decorators.
+For this, the `eduvpn.EduVPN` class has the following syntax:
+
+```python
+# Where _eduvpn is the eduvpn.EduVPN class instance
+# This gets called when the New_State_Example state is entered
+# old_state is then the old state
+@_eduvpn.event.on("New_State_Example", eduvpn.StateType.Enter)
+def example_enter(old_state: str, data: str)
+```
+```python
+# Where _eduvpn is the eduvpn.EduVPN class instance
+# This gets called when the New_State_Example state is left
+# new_state is then the new state
+@_eduvpn.event.on("New_State_Example", eduvpn.StateType.Leave)
+def example_leave(new_state: str, data: str)
+```
+To show how this can be done in practice, we will give an example in the next section.