Docs Exports: Add some example input/output

2 files changed, 559 insertions, 50 deletions

diff --git a/docs/src/api/functiondocs.md b/docs/src/api/functiondocs.md
index 854dd01..1f31871 100644
--- a/docs/src/api/functiondocs.md
+++ b/docs/src/api/functiondocs.md
@@ -35,7 +35,7 @@ Some notes:
 
 - Errors are returned as JSON c strings. The JSON type is defined in
 types/error/error.go Error. Free them using FreeString. Same is the case for
-other string types, you should also free them
+other string types, you should also free them. The errors are always localized
 
 - Types are converted from the Go representation to C using JSON strings
 
@@ -80,9 +80,7 @@ This `ni` flag is useful for preprovisioned servers. For normal usage,
 you want to set this to zero (meaning: False)
 
 If the server cannot be added it returns the error as types/error/error.go
-Error
-
-# Note that the server is removed when an error has occured
+Error. Note that the server is removed when an error has occured
 
 The following state callbacks are mandatory to handle:
 
@@ -90,6 +88,18 @@ The following state callbacks are mandatory to handle:
     it returns the URL as the data. The client should open the webbrowser
     with this URL and continue the authorization process.
 
+Example Input (3=custom server): ```AddServer(mycookie, 3,
+"https://demo.eduvpn.nl", 0)```
+
+Example Output:
+
+    {
+      "message": {
+        "en": "failed to add server"
+      },
+      "misc": false
+    }
+
 ## Cleanup
 Signature:
  ```go
@@ -101,7 +111,18 @@ This MUST be called when disconnecting, see
 https://docs.eduvpn.org/server/v3/api.html#application-flow `c` is the
 Cookie that needs to be passed. Create a new Cookie using `CookieNew`
 
-If it was unsuccessful, it returns an error
+If it was unsuccessful, it returns an error.
+
+Example Input: ```Cleanup(myCookie)```
+
+Example Output:
+
+    {
+      "message": {
+        "en": "cleanup was not successful"
+      },
+      "misc": false
+    }
 
 ## CookieCancel
 Signature:
@@ -115,7 +136,9 @@ they're still running The error cause is always context.Canceled for that
 cancelled function: https://pkg.go.dev/context#pkg-variables
 
 This CookieCancel function can also return an error if cancelling was
-unsuccessful
+unsuccessful Example Input: ```CookieCancel(myCookie)```
+
+Example Output: null
 
 ## CookieDelete
 Signature:
@@ -126,23 +149,18 @@ CookieDelete deletes the cookie by cancelling it and deleting the underlying
 cgo handle
 
 This function MUST be called when the cookie that is created using
-`CookieNew` is no longer needed
+`CookieNew` is no longer needed. Example Input: ```CookieDelete(myCookie)```
+
+Example Output: null
 
 ## CookieNew
 Signature:
  ```go
 func CookieNew() C.uintptr_t
 ```
-CookieNew creates a new cookie and returns it
-
-This value should not be parsed or converted somehow by the client This
-value is simply to pass back to the Go library This value has two purposes:
-
-  - Cancel a long running function
-
-  - Send a reply to a state transition (ASK_PROFILE and ASK_LOCATION)
+Example Input: ```CookieNew()```
 
-Functions that take a cookie have it as the first argument
+Example Output: ```5```
 
 ## CookieReply
 Signature:
@@ -158,6 +176,10 @@ function
 
   - `data` is the data to send, e.g. a profile ID
 
+Example Input: ```CookieReply(myCookie, "split-tunnel-profile")```
+
+Example Output: ```null```
+
 ## CurrentServer
 Signature:
  ```go
@@ -173,6 +195,47 @@ It returns the server as JSON, defined in types/server/server.go Current
 If there is no current server or some other, e.g. there is no current state,
 an error is returned with a nil string
 
+Example Input: ```CurrentServer()```
+
+Example Output:
+
+    {
+      "institute_access_server": {
+        "display_name": {
+          "en": "Demo"
+        },
+        "identifier": "https://demo.eduvpn.nl/",
+        "profiles": {
+          "map": {
+            "internet": {
+              "display_name": {
+                "en": "Internet"
+              },
+              "supported_protocols": [
+                1,
+                2
+              ]
+            },
+            "internet-split": {
+              "display_name": {
+                "en": "No rfc1918 routes"
+              },
+              "supported_protocols": [
+                1,
+                2
+              ]
+            }
+          },
+          "current": "internet"
+        },
+        "support_contacts": [
+          "mailto:eduvpn@surf.nl"
+        ],
+        "delisted": false
+      },
+      "server_type": 1
+    }, null
+
 ## Deregister
 Signature:
  ```go
@@ -180,14 +243,25 @@ func Deregister() *C.char
 ```
 Deregister cleans up the state for the client.
 
-# If no client is available or deregistering fails, it returns an error
-
 This function SHOULD be called when the application exits such that the
 configuration file is saved correctly. Note that saving of the configuration
 file also happens in other cases, such as after getting a VPN configuration.
 Thus it is often not problematic if this function cannot be called due to a
 client crash
 
+If no client is available or deregistering fails, it returns an error.
+
+Example Input: ```Deregister()```
+
+Example Output:
+
+    {
+      "message": {
+        "en": "failed to deregister"
+      },
+      "misc": false
+    }
+
 ## DiscoOrganizations
 Signature:
  ```go
@@ -203,6 +277,37 @@ If it was unsuccessful, it returns an error. Note that when the lib was
 built in release mode the data is almost always non-nil, even when an error
 has occurred This means it has just returned the cached list
 
+Example Input: ```DiscoOrganizations(myCookie)```
+
+Example Output:
+
+    {
+     "v": 1695291170,
+     "organization_list": [
+       {
+         "display_name": {
+           "en": "Academic Network of Albania - RASH"
+         },
+         "org_id": "https://idp.rash.al/simplesaml/saml2/idp/metadata.php",
+         "secure_internet_home": "https://eduvpn.rash.al/"
+       },
+       {
+         "display_name": {
+           "da": "Dansk Sprognævn",
+           "en": "Danish Language Council"
+         },
+         "org_id": "http://idp.dsn.dk/adfs/services/trust",
+         "secure_internet_home": "https://eduvpn.deic.dk/"
+       },
+       {
+         "display_name": {
+           "da": "Erhvervsakademi Aarhus",
+           "en": "Business Academy Aarhus"
+         },
+         "org_id": "http://adfs.eaaa.dk/adfs/services/trust",
+         "secure_inte .....................
+    }, null
+
 ## DiscoServers
 Signature:
  ```go
@@ -218,6 +323,32 @@ If it was unsuccessful, it returns an error. Note that when the lib was
 built in release mode the data is almost always non-nil, even when an error
 has occurred This means it has just returned the cached list
 
+Example Input: ```DiscoServers(myCookie)```
+
+Example Output:
+
+    {
+     "v": 1695291170,
+     "server_list": [
+       {
+         "base_url": "https://eduvpn.rash.al/",
+         "country_code": "AL",
+         "public_key_list": [
+           "k7.pub.S4j5JJiTEz1fWMkI.hzU_xJasWzD6Da2WR7hgbobx9n3o4XSDeqFh03tgM-0"
+         ],
+         "server_type": "secure_internet",
+         "support_contact": [
+           "mailto:helpdesk@rash.al"
+         ]
+       },
+       {
+         "base_url": "https://eduvpn.deic.dk/",
+         "country_code": "DK",
+         "public_key_list": [
+           "k7.pub.RNOJIYbemlfsE7EL.BxmV2l2UV7pCqz135ofBgyG9-xLg0R9rILQedZrfLtE"
+         ], ..................
+    } , null
+
 ## ExpiryTimes
 Signature:
  ```go
@@ -232,6 +363,21 @@ when to show expiry notifications
 The expiry times structure is defined in types/server/server.go `Expiry` If
 some error occurs, it is returned as types/error/error.go Error
 
+Example Input: ```ExpiryTimes()```
+
+Example Output (1...4 are unix timestamps):
+
+    {
+         "start_time": 1,
+         "end_time": 2,
+         "button_time": 3,
+         "countdown_time": 4,
+         "notification_times": [
+             1,
+             2,
+         ],
+    }, null
+
 ## FreeString
 Signature:
  ```go
@@ -243,6 +389,8 @@ This happens when we return strings, such as errors from the Go lib back to
 the client. The client MUST thus ensure that this memory is freed using this
 function. Simply pass the pointer to the string in here
 
+Example Input: ```FreeString(strPtr)```
+
 ## GetConfig
 Signature:
  ```go
@@ -342,6 +490,17 @@ The client should open the webbrowser with this URL and continue the
 authorization process. This is only called if authorization needs to be
 retriggered
 
+Example Input (3=custom server): ```GetConfig(myCookie, 3,
+"https://demo.eduvpn.nl/", 0, 0)```
+
+Example Output (2=WireGuard):
+
+    {
+     "config": "https://demo.eduvpn.nl/\n# Profile: ...\n# Expires: ...\n\n[Interface]\nPrivateKey = ...\nAddress = ...\nDNS = ...\n\n[Peer]\nPublicKey = ...=\nAllowedIPs = 0.0.0.0/0,::/0\nEndpoint = ...",
+     "protocol": 2,
+     "default_gateway": true
+    }
+
 ## InState
 Signature:
  ```go
@@ -349,6 +508,10 @@ func InState(fsmState C.int) (C.int, *C.char)
 ```
 InState checks if the FSM is in `fsmState`
 
+Example Input: ```InState(5)```
+
+Example Output: ```1, null```
+
 ## Register
 Signature:
  ```go
@@ -389,6 +552,18 @@ After registering, the FSM is initialized and the state transition NO_SERVER
 should have been completed If some error occurs during registering, it is
 returned as a types/error/error.go Error
 
+Example Input: ```Register("org.eduvpn.app.linux", "0.0.1",
+"/tmp/eduvpn-common", myCallbackFunc, 1)```
+
+Example Output:
+
+    {
+      "message": {
+        "en": "failed to register, a VPN state is already present"
+      },
+      "misc": false
+    }
+
 ## RemoveServer
 Signature:
  ```go
@@ -408,9 +583,18 @@ in types/server/server.go Type
   - In case of institute access: The base URL
 
 If the server cannot be removed it returns the error types/error/error.go
-Error
+Error.
+
+Example Input (3=custom server): ```RemoveServer(3, "bogus")```
+
+Example Output:
 
-Note that the server is not removed when an error has occured
+    {
+      "message": {
+        "en": "failed to remove server"
+      },
+      "misc": false
+    }
 
 ## RenewSession
 Signature:
@@ -423,7 +607,17 @@ This essentially means that the OAuth tokens are deleted. And it also
 possibly re-runs every state callback you need when getting a config.
 So least you MUST handle the OAuth started transition
 
-It returns an error if unsuccessful
+It returns an error if unsuccessful. Example Input:
+```RenewSession(myCookie)```
+
+Example Output:
+
+    {
+      "message": {
+        "en": "could not renew session"
+      },
+      "misc": false
+    }
 
 ## ServerList
 Signature:
@@ -436,9 +630,30 @@ This is NOT the discovery list, but the servers that have previously been
 added with `AddServer`
 
 It returns the server list as a JSON string defined in
-types/server/server.go List
-
-If the server list cannot be retrieved it returns a nil string and an error
+types/server/server.go List. If the server list cannot be retrieved it
+returns a nil string and an error
+
+Example Input: ```ServerList()```
+
+Example Output (current profile here is empty as none has been chosen yet):
+
+    {
+      "institute_access_servers": [
+        {
+          "display_name": {
+            "en": "Demo"
+          },
+          "identifier": "https://demo.eduvpn.nl/",
+          "profiles": {
+            "current": ""
+          },
+          "support_contacts": [
+            "mailto:eduvpn@surf.nl"
+          ],
+          "delisted": false
+        }
+      ]
+    }, null
 
 ## SetProfileID
 Signature:
@@ -452,7 +667,17 @@ instead of the common lib asking for one using a transition
 
 `Data` is the profile ID
 
-It returns an error if unsuccessful
+It returns an error if unsuccessful. Example Input:
+```SetProfileID("splittunnel")```
+
+Example Output:
+
+    {
+      "message": {
+        "en": "profile does not exist"
+      },
+      "misc": false
+    }
 
 ## SetSecureLocation
 Signature:
@@ -471,7 +696,17 @@ cookie again :)
 `c` is the Cookie that needs to be passed. To create a cookie, first call
 `CookieNew` `Data` is the location ID
 
-It returns an error if unsuccessful
+It returns an error if unsuccessful. Example Input:
+```SetSecureLocation("nl")```
+
+Example Output:
+
+    {
+      "message": {
+        "en": "location does not exist"
+      },
+      "misc": false
+    }
 
 ## SetState
 Signature:
@@ -481,14 +716,17 @@ func SetState(fsmState C.int) *C.char
 SetState sets the state of the statemachine
 
 Note: this transitions the FSM into the new state without passing any data
-to it
+to it. Example Input: ```SetState(5)```
+
+Example Output: ```null```
 
 ## SetSupportWireguard
 Signature:
  ```go
 func SetSupportWireguard(support C.int) *C.char
 ```
-SetSupportWireguard enables or disables WireGuard for the client
+SetSupportWireguard enables or disables WireGuard for the client. *WARNING:
+This function will be removed*
 
 By default WireGuard support is enabled To disable it you can pass a 0 int
 to this
@@ -530,7 +768,10 @@ setter is the void function that sets tokens. It takes two arguments:
   - The `tokens`, defined in types/server/server.go `Tokens` marshalled as
     JSON
 
-It returns an error when the tokens cannot be set
+It returns an error when the tokens cannot be set. Example Input:
+```SetTokenHandler(getterFunc, setterFunc)```
+
+Example Output: ```null```
 
 ## StartFailover
 Signature:
@@ -550,9 +791,13 @@ WireGuard connection to OpenVPN over TCP
   - `readRxBytes` is a function that returns the current rx bytes of the VPN
     interface, this should return a `long long int` in c
 
-It returns a boolean whether or not the common lib has determined that it
-cannot reach the gateway. Non-zero=dropped, zero=not dropped.
-
+It returns a boolean whether or not the common lib has determined
+that it cannot reach the gateway. Non-zero=dropped, zero=not dropped.
 It also returns an error, if it fails to indicate if it has dropped or not.
 In this case, dropped is also set to zero
 
+Example Input: ```StartFailover(myCookie, "10.10.10.1", 1400,
+myRxBytesReader)```
+
+Example Output: ```1, null```
+
diff --git a/exports/exports.go b/exports/exports.go
index a68dea9..65f1fdd 100644
--- a/exports/exports.go
+++ b/exports/exports.go
@@ -2,7 +2,7 @@
 //
 // Some notes:
 //
-// - Errors are returned as JSON c strings. The JSON type is defined in types/error/error.go Error. Free them using FreeString. Same is the case for other string types, you should also free them
+// - Errors are returned as JSON c strings. The JSON type is defined in types/error/error.go Error. Free them using FreeString. Same is the case for other string types, you should also free them. The errors are always localized
 //
 // - Types are converted from the Go representation to C using JSON strings
 //
@@ -144,6 +144,18 @@ func getVPNState() (*client.Client, error) {
 // After registering, the FSM is initialized and the state transition NO_SERVER should have been completed
 // If some error occurs during registering, it is returned as a types/error/error.go Error
 //
+// Example Input:
+// ```Register("org.eduvpn.app.linux", "0.0.1", "/tmp/eduvpn-common", myCallbackFunc, 1)```
+//
+// Example Output:
+//
+//    {
+//      "message": {
+//        "en": "failed to register, a VPN state is already present"
+//      },
+//      "misc": false
+//    }
+//
 //export Register
 func Register(
 	name *C.char,
@@ -191,6 +203,21 @@ func Register(
 // The expiry times structure is defined in types/server/server.go `Expiry`
 // If some error occurs, it is returned as types/error/error.go Error
 //
+// Example Input:
+// ```ExpiryTimes()```
+//
+// Example Output (1...4 are unix timestamps):
+//    {
+//         "start_time": 1,
+//         "end_time": 2,
+//         "button_time": 3,
+//         "countdown_time": 4,
+//         "notification_times": [
+//             1,
+//             2,
+//         ],
+//    }, null
+//
 //export ExpiryTimes
 func ExpiryTimes() (*C.char, *C.char) {
 	state, stateErr := getVPNState()
@@ -210,12 +237,25 @@ func ExpiryTimes() (*C.char, *C.char) {
 
 // Deregister cleans up the state for the client.
 //
-// If no client is available or deregistering fails, it returns an error
-//
 // This function SHOULD be called when the application exits such that the configuration file is saved correctly.
 // Note that saving of the configuration file also happens in other cases, such as after getting a VPN configuration.
 // Thus it is often not problematic if this function cannot be called due to a client crash
 //
+// If no client is available or deregistering fails, it returns an error.
+//
+// Example Input:
+// ```Deregister()```
+//
+// Example Output:
+//
+//    {
+//      "message": {
+//        "en": "failed to deregister"
+//      },
+//      "misc": false
+//    }
+//
+//
 //export Deregister
 func Deregister() *C.char {
 	state, stateErr := getVPNState()
@@ -244,8 +284,7 @@ func Deregister() *C.char {
 //
 // This `ni` flag is useful for preprovisioned servers. For normal usage, you want to set this to zero (meaning: False)
 //
-// If the server cannot be added it returns the error as types/error/error.go Error
-//
+// If the server cannot be added it returns the error as types/error/error.go Error.
 // Note that the server is removed when an error has occured
 //
 // The following state callbacks are mandatory to handle:
@@ -253,6 +292,19 @@ func Deregister() *C.char {
 //   - OAUTH_STARTED: This indicates that the OAuth procedure has been started, it returns the URL as the data.
 //     The client should open the webbrowser with this URL and continue the authorization process.
 //
+// Example Input (3=custom server):
+// ```AddServer(mycookie, 3, "https://demo.eduvpn.nl", 0)```
+//
+// Example Output:
+//
+//    {
+//      "message": {
+//        "en": "failed to add server"
+//      },
+//      "misc": false
+//    }
+//
+//
 //export AddServer
 func AddServer(c C.uintptr_t, _type C.int, id *C.char, ni C.int) *C.char {
 	// TODO: type
@@ -280,9 +332,19 @@ func AddServer(c C.uintptr_t, _type C.int, id *C.char, ni C.int) *C.char {
 //
 //   - In case of institute access: The base URL
 //
-// If the server cannot be removed it returns the error types/error/error.go Error
+// If the server cannot be removed it returns the error types/error/error.go Error.
+//
+// Example Input (3=custom server):
+// ```RemoveServer(3, "bogus")```
 //
-// Note that the server is not removed when an error has occured
+// Example Output:
+//
+//    {
+//      "message": {
+//        "en": "failed to remove server"
+//      },
+//      "misc": false
+//    }
 //
 //export RemoveServer
 func RemoveServer(_type C.int, id *C.char) *C.char {
@@ -302,6 +364,47 @@ func RemoveServer(_type C.int, id *C.char) *C.char {
 //
 // If there is no current server or some other, e.g. there is no current state, an error is returned with a nil string
 //
+// Example Input:
+// ```CurrentServer()```
+//
+// Example Output:
+//    {
+//      "institute_access_server": {
+//        "display_name": {
+//          "en": "Demo"
+//        },
+//        "identifier": "https://demo.eduvpn.nl/",
+//        "profiles": {
+//          "map": {
+//            "internet": {
+//              "display_name": {
+//                "en": "Internet"
+//              },
+//              "supported_protocols": [
+//                1,
+//                2
+//              ]
+//            },
+//            "internet-split": {
+//              "display_name": {
+//                "en": "No rfc1918 routes"
+//              },
+//              "supported_protocols": [
+//                1,
+//                2
+//              ]
+//            }
+//          },
+//          "current": "internet"
+//        },
+//        "support_contacts": [
+//          "mailto:eduvpn@surf.nl"
+//        ],
+//        "delisted": false
+//      },
+//      "server_type": 1
+//    }, null
+//
 //export CurrentServer
 func CurrentServer() (*C.char, *C.char) {
 	state, stateErr := getVPNState()
@@ -323,10 +426,33 @@ func CurrentServer() (*C.char, *C.char) {
 //
 // This is NOT the discovery list, but the servers that have previously been added with `AddServer`
 //
-// It returns the server list as a JSON string defined in types/server/server.go List
-//
+// It returns the server list as a JSON string defined in types/server/server.go List.
 // If the server list cannot be retrieved it returns a nil string and an error
 //
+// Example Input:
+// ```ServerList()```
+//
+// Example Output (current profile here is empty as none has been chosen yet):
+//
+//    {
+//      "institute_access_servers": [
+//        {
+//          "display_name": {
+//            "en": "Demo"
+//          },
+//          "identifier": "https://demo.eduvpn.nl/",
+//          "profiles": {
+//            "current": ""
+//          },
+//          "support_contacts": [
+//            "mailto:eduvpn@surf.nl"
+//          ],
+//          "delisted": false
+//        }
+//      ]
+//    }, null
+//
+//
 //export ServerList
 func ServerList() (*C.char, *C.char) {
 	state, stateErr := getVPNState()
@@ -421,6 +547,17 @@ func ServerList() (*C.char, *C.char) {
 // The client should open the webbrowser with this URL and continue the authorization process.
 // This is only called if authorization needs to be retriggered
 //
+// Example Input (3=custom server):
+// ```GetConfig(myCookie, 3, "https://demo.eduvpn.nl/", 0, 0)```
+//
+// Example Output (2=WireGuard):
+//
+//    {
+//     "config": "https://demo.eduvpn.nl/\n# Profile: ...\n# Expires: ...\n\n[Interface]\nPrivateKey = ...\nAddress = ...\nDNS = ...\n\n[Peer]\nPublicKey = ...=\nAllowedIPs = 0.0.0.0/0,::/0\nEndpoint = ...",
+//     "protocol": 2,
+//     "default_gateway": true
+//    }
+//
 //export GetConfig
 func GetConfig(c C.uintptr_t, _type C.int, id *C.char, pTCP C.int, startup C.int) (*C.char, *C.char) {
 	state, stateErr := getVPNState()
@@ -449,7 +586,17 @@ func GetConfig(c C.uintptr_t, _type C.int, id *C.char, pTCP C.int, startup C.int
 //
 // `Data` is the profile ID
 //
-// It returns an error if unsuccessful
+// It returns an error if unsuccessful.
+// Example Input: ```SetProfileID("splittunnel")```
+//
+// Example Output:
+//
+//    {
+//      "message": {
+//        "en": "profile does not exist"
+//      },
+//      "misc": false
+//    }
 //
 //export SetProfileID
 func SetProfileID(data *C.char) *C.char {
@@ -470,7 +617,17 @@ func SetProfileID(data *C.char) *C.char {
 // `c` is the Cookie that needs to be passed. To create a cookie, first call `CookieNew`
 // `Data` is the location ID
 //
-// It returns an error if unsuccessful
+// It returns an error if unsuccessful.
+// Example Input: ```SetSecureLocation("nl")```
+//
+// Example Output:
+//
+//    {
+//      "message": {
+//        "en": "location does not exist"
+//      },
+//      "misc": false
+//    }
 //
 //export SetSecureLocation
 func SetSecureLocation(c C.uintptr_t, data *C.char) *C.char {
@@ -493,6 +650,32 @@ func SetSecureLocation(c C.uintptr_t, data *C.char) *C.char {
 // If it was unsuccessful, it returns an error. Note that when the lib was built in release mode the data is almost always non-nil, even when an error has occurred
 // This means it has just returned the cached list
 //
+// Example Input: ```DiscoServers(myCookie)```
+//
+// Example Output:
+//
+//     {
+//      "v": 1695291170,
+//      "server_list": [
+//        {
+//          "base_url": "https://eduvpn.rash.al/",
+//          "country_code": "AL",
+//          "public_key_list": [
+//            "k7.pub.S4j5JJiTEz1fWMkI.hzU_xJasWzD6Da2WR7hgbobx9n3o4XSDeqFh03tgM-0"
+//          ],
+//          "server_type": "secure_internet",
+//          "support_contact": [
+//            "mailto:helpdesk@rash.al"
+//          ]
+//        },
+//        {
+//          "base_url": "https://eduvpn.deic.dk/",
+//          "country_code": "DK",
+//          "public_key_list": [
+//            "k7.pub.RNOJIYbemlfsE7EL.BxmV2l2UV7pCqz135ofBgyG9-xLg0R9rILQedZrfLtE"
+//          ], ..................
+//     } , null
+//
 //export DiscoServers
 func DiscoServers(c C.uintptr_t) (*C.char, *C.char) {
 	state, stateErr := getVPNState()
@@ -521,6 +704,36 @@ func DiscoServers(c C.uintptr_t) (*C.char, *C.char) {
 // If it was unsuccessful, it returns an error. Note that when the lib was built in release mode the data is almost always non-nil, even when an error has occurred
 // This means it has just returned the cached list
 //
+// Example Input: ```DiscoOrganizations(myCookie)```
+//
+// Example Output:
+//    {
+//     "v": 1695291170,
+//     "organization_list": [
+//       {
+//         "display_name": {
+//           "en": "Academic Network of Albania - RASH"
+//         },
+//         "org_id": "https://idp.rash.al/simplesaml/saml2/idp/metadata.php",
+//         "secure_internet_home": "https://eduvpn.rash.al/"
+//       },
+//       {
+//         "display_name": {
+//           "da": "Dansk Sprognævn",
+//           "en": "Danish Language Council"
+//         },
+//         "org_id": "http://idp.dsn.dk/adfs/services/trust",
+//         "secure_internet_home": "https://eduvpn.deic.dk/"
+//       },
+//       {
+//         "display_name": {
+//           "da": "Erhvervsakademi Aarhus",
+//           "en": "Business Academy Aarhus"
+//         },
+//         "org_id": "http://adfs.eaaa.dk/adfs/services/trust",
+//         "secure_inte .....................
+//    }, null
+//
 //export DiscoOrganizations
 func DiscoOrganizations(c C.uintptr_t) (*C.char, *C.char) {
 	state, stateErr := getVPNState()
@@ -547,8 +760,18 @@ func DiscoOrganizations(c C.uintptr_t) (*C.char, *C.char) {
 // This MUST be called when disconnecting, see https://docs.eduvpn.org/server/v3/api.html#application-flow
 // `c` is the Cookie that needs to be passed. Create a new Cookie using `CookieNew`
 //
-// If it was unsuccessful, it returns an error
+// If it was unsuccessful, it returns an error.
+//
+// Example Input: ```Cleanup(myCookie)```
 //
+// Example Output:
+//
+//    {
+//      "message": {
+//        "en": "cleanup was not successful"
+//      },
+//      "misc": false
+//    }
 //export Cleanup
 func Cleanup(c C.uintptr_t) *C.char {
 	state, stateErr := getVPNState()
@@ -569,7 +792,17 @@ func Cleanup(c C.uintptr_t) *C.char {
 // And it also possibly re-runs every state callback you need when getting a config.
 // So least you MUST handle the OAuth started transition
 //
-// It returns an error if unsuccessful
+// It returns an error if unsuccessful.
+// Example Input: ```RenewSession(myCookie)```
+//
+// Example Output:
+//
+//    {
+//      "message": {
+//        "en": "could not renew session"
+//      },
+//      "misc": false
+//    }
 //
 //export RenewSession
 func RenewSession(c C.uintptr_t) *C.char {
@@ -585,7 +818,8 @@ func RenewSession(c C.uintptr_t) *C.char {
 	return getCError(renewSessionErr)
 }
 
-// SetSupportWireguard enables or disables WireGuard for the client
+// SetSupportWireguard enables or disables WireGuard for the client.
+// *WARNING: This function will be removed*
 //
 // By default WireGuard support is enabled
 // To disable it you can pass a 0 int to this
@@ -593,6 +827,7 @@ func RenewSession(c C.uintptr_t) *C.char {
 // `support` thus indicates whether or not to enable WireGuard
 // An error is returned if this is not possible
 //
+//
 //export SetSupportWireguard
 func SetSupportWireguard(support C.int) *C.char {
 	state, stateErr := getVPNState()
@@ -614,9 +849,12 @@ func SetSupportWireguard(support C.int) *C.char {
 //   - `readRxBytes` is a function that returns the current rx bytes of the VPN interface, this should return a `long long int` in c
 //
 // It returns a boolean whether or not the common lib has determined that it cannot reach the gateway. Non-zero=dropped, zero=not dropped.
-//
 // It also returns an error, if it fails to indicate if it has dropped or not. In this case, dropped is also set to zero
 //
+// Example Input: ```StartFailover(myCookie, "10.10.10.1", 1400, myRxBytesReader)```
+//
+// Example Output: ```1, null```
+//
 //export StartFailover
 func StartFailover(c C.uintptr_t, gateway *C.char, mtu C.int, readRxBytes C.ReadRxBytes) (C.int, *C.char) {
 	state, stateErr := getVPNState()
@@ -646,7 +884,10 @@ func StartFailover(c C.uintptr_t, gateway *C.char, mtu C.int, readRxBytes C.Read
 
 // SetState sets the state of the statemachine
 //
-// Note: this transitions the FSM into the new state without passing any data to it
+// Note: this transitions the FSM into the new state without passing any data to it.
+// Example Input: ```SetState(5)```
+//
+// Example Output: ```null```
 //
 //export SetState
 func SetState(fsmState C.int) *C.char {
@@ -659,6 +900,10 @@ func SetState(fsmState C.int) *C.char {
 
 // InState checks if the FSM is in `fsmState`
 //
+// Example Input: ```InState(5)```
+//
+// Example Output: ```1, null```
+//
 //export InState
 func InState(fsmState C.int) (C.int, *C.char) {
 	state, stateErr := getVPNState()
@@ -678,6 +923,8 @@ func InState(fsmState C.int) (C.int, *C.char) {
 // The client MUST thus ensure that this memory is freed using this function.
 // Simply pass the pointer to the string in here
 //
+// Example Input: ```FreeString(strPtr)```
+//
 //export FreeString
 func FreeString(addr *C.char) {
 	C.free(unsafe.Pointer(addr))
@@ -720,7 +967,10 @@ func getCookie(c C.uintptr_t) (*cookie.Cookie, error) {
 //
 //   - The `tokens`, defined in types/server/server.go `Tokens` marshalled as JSON
 //
-// It returns an error when the tokens cannot be set
+// It returns an error when the tokens cannot be set.
+// Example Input: ```SetTokenHandler(getterFunc, setterFunc)```
+//
+// Example Output: ```null```
 //
 //export SetTokenHandler
 func SetTokenHandler(getter C.TokenGetter, setter C.TokenSetter) *C.char {
@@ -790,6 +1040,10 @@ func SetTokenHandler(getter C.TokenGetter, setter C.TokenSetter) *C.char {
 //   - Send a reply to a state transition (ASK_PROFILE and ASK_LOCATION)
 //
 // Functions that take a cookie have it as the first argument
+
+// Example Input: ```CookieNew()```
+//
+// Example Output: ```5```
 //
 //export CookieNew
 func CookieNew() C.uintptr_t {
@@ -805,6 +1059,10 @@ func CookieNew() C.uintptr_t {
 //
 //   - `data` is the data to send, e.g. a profile ID
 //
+// Example Input: ```CookieReply(myCookie, "split-tunnel-profile")```
+//
+// Example Output: ```null```
+//
 //export CookieReply
 func CookieReply(c C.uintptr_t, data *C.char) *C.char {
 	v, err := getCookie(c)
@@ -817,7 +1075,10 @@ func CookieReply(c C.uintptr_t, data *C.char) *C.char {
 
 // CookieDelete deletes the cookie by cancelling it and deleting the underlying cgo handle
 //
-// This function MUST be called when the cookie that is created using `CookieNew` is no longer needed
+// This function MUST be called when the cookie that is created using `CookieNew` is no longer needed.
+// Example Input: ```CookieDelete(myCookie)```
+//
+// Example Output: null
 //
 //export CookieDelete
 func CookieDelete(c C.uintptr_t) *C.char {
@@ -837,6 +1098,9 @@ func CookieDelete(c C.uintptr_t) *C.char {
 // The error cause is always context.Canceled for that cancelled function: https://pkg.go.dev/context#pkg-variables
 //
 // This CookieCancel function can also return an error if cancelling was unsuccessful
+// Example Input: ```CookieCancel(myCookie)```
+//
+// Example Output: null
 //
 //export CookieCancel
 func CookieCancel(c C.uintptr_t) *C.char {