Exports: Cleanup function docs

1 files changed, 142 insertions, 136 deletions

diff --git a/docs/src/api/functiondocs.md b/docs/src/api/functiondocs.md
index c1b1122..501c8f7 100644
--- a/docs/src/api/functiondocs.md
+++ b/docs/src/api/functiondocs.md
@@ -36,7 +36,7 @@ package main implements the main exported API to be used by other languages
 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
+`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
@@ -62,17 +62,15 @@ func AddServer(c C.uintptr_t, _type C.int, id *C.char, ot *C.longlong) *C.char
 ```
 AddServer adds a server to the eduvpn-common server list `c` is the cookie
 that is used for cancellation. Create a cookie first with CookieNew.
-This same cookie is also used for replying to state transitions
+This same cookie is also used for replying to state transitions.
 
 `_type` is the type of server that needs to be added. This type is defined
-in types/server/server.go Type
+in `types/server/server.go Type`
 
 `id` is the identifier of the string:
 
   - In case of secure internet: The organization ID
-
   - In case of custom server: The base URL
-
   - In case of institute access: The base URL
 
 `ni` stands for non-interactive. If non-zero, any state transitions will not
@@ -84,8 +82,8 @@ last triggered, if the server needs to be added non-interactively but there
 is no token structure, set this to zero (integer) or the current Unix time.
 This value will be overwritten once OAuth is triggered.
 
-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
+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:
 
@@ -120,9 +118,12 @@ Signature:
 func CalculateGateway(subnet *C.char) (*C.char, *C.char)
 ```
 CalculateGateway calculates the gateway for a subnet, it can take IPv4 or
-IPv6 networks with CIDR notation as inputs and returns the gateway address
-This is useful to pass to `StartFailover`. It returns an error if it fails
-to calculate a gateway.
+IPv6 networks with CIDR notation as inputs and returns the gateway address.
+
+This is useful to pass to `StartFailover`.
+It returns an error if it fails to calculate a gateway.
+The function is implemented according to: [the eduVPN
+docs](https://docs.eduvpn.org/server/v3/client-implementation-notes.html#fail-over).
 
 Example Input: ```CalculateGateway("10.10.0.5/24")```
 
@@ -133,12 +134,12 @@ Signature:
  ```go
 func Cleanup(c C.uintptr_t) *C.char
 ```
-Cleanup sends a /disconnect to cleanup the connection. Additionally,
+Cleanup sends a `/disconnect` to cleanup the connection. Additionally,
 if ProxyGuard is active it cancels the running process
 
-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`
+This MUST be called when disconnecting, see [the eduVPN
+docs](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.
 
@@ -158,14 +159,15 @@ Signature:
  ```go
 func CookieCancel(c C.uintptr_t) *C.char
 ```
-CookieCancel cancels the cookie
+CookieCancel cancels the cookie.
 
-This means that functions which take this as first argument, return if
-they're still running The error cause is always context.Canceled for that
-cancelled function: https://pkg.go.dev/context#pkg-variables
+This means that functions which take this as first argument,
+return if they're still running. The error cause is always
+`context.Canceled` for that cancelled function: [see the Go
+docs](https://pkg.go.dev/context#pkg-variables).
 
 This CookieCancel function can also return an error if cancelling was
-unsuccessful Example Input: ```CookieCancel(myCookie)```
+unsuccessful. Example Input: ```CookieCancel(myCookie)```
 
 Example Output: null
 
@@ -175,7 +177,7 @@ Signature:
 func CookieDelete(c C.uintptr_t) *C.char
 ```
 CookieDelete deletes the cookie by cancelling it and deleting the underlying
-cgo handle
+cgo handle.
 
 This function MUST be called when the cookie that is created using
 `CookieNew` is no longer needed. Example Input: ```CookieDelete(myCookie)```
@@ -187,13 +189,12 @@ Signature:
  ```go
 func CookieNew() C.uintptr_t
 ```
-CookieNew creates a new cookie and returns it
+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:
+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)
 
 # Functions that take a cookie have it as the first argument
@@ -207,13 +208,9 @@ Signature:
  ```go
 func CookieReply(c C.uintptr_t, data *C.char) *C.char
 ```
-CookieReply replies to a state transition using the cookie
-
-The data that is sent to the Go library is the second argument of this
-function
+CookieReply replies to a state transition using the cookie.
 
   - `c` is the Cookie
-
   - `data` is the data to send, e.g. a profile ID
 
 Example Input: ```CookieReply(myCookie, "split-tunnel-profile")```
@@ -230,10 +227,10 @@ CurrentServer gets the current server from eduvpn-common
 In eduvpn-common, a server is marked as 'current' if you have gotten a VPN
 configuration for it
 
-It returns the server as JSON, defined in types/server/server.go Current
+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
+an error is returned with a nil string.
 
 Example Input: ```CurrentServer()```
 
@@ -287,7 +284,7 @@ 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
+client crash.
 
 If no client is available or deregistering fails, it returns an error.
 
@@ -308,18 +305,23 @@ Signature:
 func DiscoOrganizations(c C.uintptr_t, search *C.char) (*C.char, *C.char)
 ```
 DiscoOrganizations gets the organizations from discovery, returned as
-types/discovery/discovery.go Organizations marshalled as JSON
+`types/discovery/discovery.go Organizations` marshalled as JSON.
+
+  - `c` is the Cookie that needs to be passed. Create a new Cookie using
+    `CookieNew`
+  - `search` is the search string for filtering the list.
 
-`c` is the Cookie that needs to be passed. Create a new Cookie using
-`CookieNew` `search` is the search string for filtering the list. If any of
-the words in the search query is not contained in any of the display names
-or keywords, the candidate is filtered. Otherwise they are ranked based on
-the levenshtein distance: https://en.wikipedia.org/wiki/Levenshtein_distance
-If search is empty it returns ALL organizations currently known in common
+If any of the words in the `search` query is not contained in
+any of the display names or keywords, the candidate is filtered.
+Otherwise they are ranked based on the levenshtein distance: [Levenshtein
+Wikipedia](https://en.wikipedia.org/wiki/Levenshtein_distance). If `search`
+is empty it returns ALL organizations currently known in common
 
 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
+has occurred This means it has just returned the cached list, the error
+should then not be handled in a fatal way. E.g. show the returned cache list
+but log the error or show the error with a warning.
 
 Example Input: ```DiscoOrganizations(myCookie, "")```
 
@@ -369,17 +371,23 @@ Signature:
 func DiscoServers(c C.uintptr_t, search *C.char) (*C.char, *C.char)
 ```
 DiscoServers gets the servers from discovery, returned as
-types/discovery/discovery.go Servers marshalled as JSON
+`types/discovery/discovery.go Servers` marshalled as JSON
 
-`c` is the Cookie that needs to be passed. Create a new Cookie using
-`CookieNew` `search` is the search string for filtering the list. If any of
-the words in the search query is not contained in any of the display names
-or keywords, the candidate is filtered. Otherwise they are ranked based on
-the levenshtein distance: https://en.wikipedia.org/wiki/Levenshtein_distance
+  - `c` is the Cookie that needs to be passed. Create a new Cookie using
+    `CookieNew`
+  - `search` is the search string for filtering the list.
+
+If any of the words in the search query is not contained in any of
+the display names or keywords, the candidate is filtered. Otherwise
+they are ranked based on the levenshtein distance: [Levenshtein
+Wikipedia](https://en.wikipedia.org/wiki/Levenshtein_distance). If `search`
+is empty it returns ALL servers currently known in common
 
 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
+has occurred. This means it has just returned the cached list, the error
+should then not be handled in a fatal way. E.g. show the returned cache list
+but log the error or show the error with a warning.
 
 Example Input: ```DiscoServers(myCookie, "")```
 
@@ -419,12 +427,14 @@ Signature:
  ```go
 func DiscoveryStartup(refresh C.RefreshList) *C.char
 ```
-DiscoveryStartup does a discovery request in the background
+DiscoveryStartup does a discovery request in the background.
+
+  - The `refresh` argument is a callback that is called when the refreshing
+    is done.
 
-The `refresh` argument is a callback that is called when the refreshing is
-done When this callback is thus called, the app SHOULD refresh the server
-list of the already configured servers This DiscoveryStartup function MUST
-be called after calling `Register`
+When this callback is thus called, the app SHOULD refresh the server list
+of the already configured servers. This DiscoveryStartup function MUST be
+called after calling `Register`.
 
 ## ExpiryTimes
 Signature:
@@ -437,8 +447,8 @@ Expiry times are just fields that represent unix timestamps at which to
 do certain events regarding expiry, e.g. when to show the renew button,
 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
+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()```
 
@@ -460,11 +470,12 @@ Signature:
  ```go
 func FreeString(addr *C.char)
 ```
-FreeString frees a string that was allocated by the eduvpn-common Go library
+FreeString frees a string that was allocated by the eduvpn-common Go
+library.
 
 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
+function. Simply pass the pointer to the string in here.
 
 Example Input: ```FreeString(strPtr)```
 
@@ -480,7 +491,7 @@ information in case WireGuard over Proxyguard is used (see the last example)
 CookieNew, this same cookie is also used for replying to state transitions
 
 `_type` is the type of server that needs to be added. This type is defined
-in types/server/server.go Type
+in `types/server/server.go Type`
 
 `id` is the identifier of the string
 
@@ -498,10 +509,10 @@ not triggered
 
 After getting a configuration, the FSM moves to the GOT_CONFIG state
 The return data is the configuration, marshalled as JSON and defined in
-types/server/server.go Configuration
+`types/server/server.go Configuration`
 
 If the config cannot be retrieved it returns an error as
-types/error/error.go Error.
+`types/error/error.go Error`.
 
 The current state callbacks MUST be handled:
 
@@ -517,20 +528,17 @@ When the user has selected a profile, reply with the choice using the
 "wireguard"). CookieReply can be done in the background as the Go library
 waits for a reply
 
-The data for this transition is defined in types/server/server.go
-RequiredAskTransition with embedded data Profiles in types/server/server.go.
-Note that RequiredTransition contains the cookie to be used for the
-CookieReply
+The data for this transition is defined in `types/server/server.go
+RequiredAskTransition` with embedded data `Profiles` in
+`types/server/server.go`. Note that `RequiredAskTransition` contains the
+cookie to be used for the `CookieReply`.
 
 So a client would:
 
-- Parse the data to get the cookie and data
-
-- get the cookie
-
-- get the profiles from the data
-
-- show it in the UI and then reply with CookieReply using the choice
+  - Parse the data to get the cookie and data
+  - get the cookie
+  - get the profiles from the data
+  - show it in the UI and then reply with CookieReply using the choice
 
 ### ASK_LOCATION
 
@@ -543,20 +551,17 @@ When the user has selected a location, reply with the choice using the
 `CookieReply` function and the location ID e.g. CookieReply(cookie, "nl")
 
 CookieReply can be done in the background as the Go library waits for a
-reply The data for this transition is defined in types/server/server.go
-RequiredAskTransition with embedded data a list of strings ([]string)
+reply The data for this transition is defined in `types/server/server.go
+RequiredAskTransition` with embedded data a list of strings (`[]string`)
 
-Note that RequiredTransition contains the cookie to be used for the
-CookieReply,
+Note that `RequiredAskTransition` contains the cookie to be used for the
+`CookieReply` function,
 
 So a client would:
 
   - Parse the data to get the cookie and data
-
   - get the cookie
-
   - get the list of locations from the data
-
   - show it in the UI and then reply with CookieReply using the choice
 
 ### OAUTH_STARTED
@@ -605,7 +610,7 @@ Signature:
  ```go
 func InState(fsmState C.int) (C.int, *C.char)
 ```
-InState checks if the FSM is in `fsmState`
+InState checks if the FSM is in `fsmState`.
 
 Example Input: ```InState(5)```
 
@@ -615,31 +620,31 @@ Example Output: ```1, null```
 Signature:
  ```go
 func Register(
-```
 	name *C.char,
 	version *C.char,
 	configDirectory *C.char,
 	cb C.StateCB,
 	debug C.int,
 ) *C.char
+```
 Register creates a new client and also registers the FSM to go to the
 initial state
 
-`Name` is the name of the client, must be a valid client ID
+`Name` is the name of the client, must be a valid client ID.
 
 `Version` is the version of the client. This version field is used for the
-user agent in all HTTP requests
+user agent in all HTTP requests.
 
 `cb` is the state callback. It takes three arguments: The old state, the new
-state and the data for the state as JSON
+state and the data for the state as JSON.
 
-  - Note that the states are defined in client/fsm.go, e.g. NO_SERVER (in
-    Go: StateNoServer), ASK_PROFILE (in Go: StateAskProfile)
+  - Note that the states are defined in client/fsm.go, e.g. `Main` (in Go:
+    `StateMain`), `ASK_PROFILE` (in Go: `StateAskProfile`)
 
   - This callback returns non-zero if the state transition is handled.
     This is used to check if the client handles the needed transitions
 
-debug, if non-zero, enables debugging mode for the library, this means:
+`debug`, if non-zero, enables debugging mode for the library, this means:
 
   - Log everything in debug mode, so you can get more detail of what is
     going on
@@ -647,9 +652,9 @@ debug, if non-zero, enables debugging mode for the library, this means:
   - Write the state graph to a file in the configDirectory. This can be used
     to create a FSM png file with mermaid https://mermaid.js.org/
 
-After registering, the FSM is initialized and the state transition NO_SERVER
+After registering, the FSM is initialized and the state transition `MAIN`
 should have been completed If some error occurs during registering, it is
-returned as a types/error/error.go Error
+returned as a `types/error/error.go Error`
 
 Example Input: ```Register("org.eduvpn.app.linux", "0.0.1",
 "/tmp/eduvpn-common", myCallbackFunc, 1)```
@@ -671,18 +676,16 @@ func RemoveServer(_type C.int, id *C.char) *C.char
 RemoveServer removes a server from the eduvpn-common server list
 
 `_type` is the type of server that needs to be added. This type is defined
-in types/server/server.go Type
+in `types/server/server.go Type`
 
 `id` is the identifier of the string:
 
   - In case of secure internet: The organization ID
-
   - In case of custom server: The base URL
-
   - 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")```
 
@@ -726,11 +729,11 @@ func ServerList() (*C.char, *C.char)
 ServerList gets the list of servers that are currently added
 
 This is NOT the discovery list, but the servers that have previously been
-added with `AddServer`
+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()```
 
@@ -759,12 +762,12 @@ Signature:
  ```go
 func SetProfileID(data *C.char) *C.char
 ```
-SetProfileID sets the profile ID of the current serrver
+SetProfileID sets the profile ID of the current serrver.
 
 This MUST only be called if the user/client wishes to manually set a profile
-instead of the common lib asking for one using a transition
+instead of the common lib asking for one using a transition.
 
-`Data` is the profile ID
+  - `data` is the profile ID.
 
 It returns an error if unsuccessful. Example Input:
 ```SetProfileID("splittunnel")```
@@ -784,13 +787,13 @@ Signature:
 func SetSecureLocation(orgID *C.char, cc *C.char) *C.char
 ```
 SetSecureLocation sets the location for the secure internet server if it
-exists
+exists.
 
 This MUST only be called if the user/client wishes to manually set a
-location instead of the common lib asking for one using a transition
+location instead of the common lib asking for one using a transition.
 
-`orgID` is the organisation ID for the secure internet server `cc` is the
-location ID/country code
+  - `orgID` is the organisation ID for the secure internet server
+  - `cc` is the location ID/country code
 
 It returns an error if unsuccessful. Example Input:
 ```SetSecureLocation("http://idp.geant.org/", "nl")```
@@ -809,7 +812,7 @@ Signature:
  ```go
 func SetState(fsmState C.int) *C.char
 ```
-SetState sets the state of the statemachine
+SetState sets the state of the state machine.
 
 Note: this transitions the FSM into the new state without passing any data
 to it. Example Input: ```SetState(5)```
@@ -821,33 +824,29 @@ Signature:
  ```go
 func SetTokenHandler(getter C.TokenGetter, setter C.TokenSetter) *C.char
 ```
-SetTokenHandler sets the token getters and token setters for OAuth
+SetTokenHandler sets the token getters and token setters for OAuth.
 
 Because the data that is saved does not contain OAuth tokens for server,
 the common lib asks and sets the tokens using these callback functions.
 The client can thus pass callbacks to this function so that the tokens can
-be securely stored in a keyring
-
-Client must pass two arguments to these functions
+be securely stored in a keyring.
 
-  - getter is the void function that gets tokens from the client. It takes
-    three arguments:
+The client must pass two callback arguments to this function:
 
+1. `getter` is the void function that gets tokens from the client. It takes
+three arguments:
   - The `server` for which to get the tokens for, marshalled as JSON and
-    defined in types/server/server.go `Current`
-
+    defined in `types/server/server.go Current`
   - The `output` buffer
-
   - The `length` of the output buffer. This 'output buffer' must contain the
-    tokens, marshalled as JSON that is defined in types/server/server.go
-    `Tokens`
+    tokens, marshalled as JSON that is defined in `types/server/server.go
+    Tokens`
 
-setter is the void function that sets tokens. It takes two arguments:
+2. `setter` is the void function that sets tokens. It takes two arguments:
 
   - The `server` for which to get the tokens for, marshalled as JSON and
-    defined in types/server/server.go `Current`
-
-  - The `tokens`, defined in types/server/server.go `Tokens` marshalled as
+    defined in `types/server/server.go Current`
+  - The `tokens`, defined in `types/server/server.go Tokens` marshalled as
     JSON
 
 It returns an error when the tokens cannot be set. Example Input:
@@ -860,12 +859,12 @@ Signature:
  ```go
 func StartFailover(c C.uintptr_t, gateway *C.char, mtu C.int, readRxBytes C.ReadRxBytes) (C.int, *C.char)
 ```
-StartFailover starts the 'failover' procedure in eduvpn-common
+StartFailover starts the 'failover' procedure in eduvpn-common.
 
 Failover has one primary goal: check if the VPN can reach the gateway.
 This can be used to check whether or not the client needs to 'failover' to
 prefer TCP (if currently using UDP). Which is useful to go from a broken
-WireGuard connection to OpenVPN over TCP
+WireGuard connection to OpenVPN over TCP.
 
   - `c` is the cookie that is passed for cancellation. To create a cookie,
     use the `CookieNew` function
@@ -877,7 +876,7 @@ WireGuard connection to OpenVPN over TCP
 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
+In this case, dropped is also set to zero.
 
 Example Input: ```StartFailover(myCookie, "10.10.10.1", 1400,
 myRxBytesReader)```
@@ -889,20 +888,24 @@ Signature:
  ```go
 func StartProxyguard(c C.uintptr_t, listen *C.char, tcpsp C.int, peer *C.char, proxySetup C.ProxySetup, proxyReady C.ProxyReady) *C.char
 ```
-StartProxyguard starts the 'proxyguard' procedure in eduvpn-common. Note
-that you should cancel/delete the cookie for this function when ProxyGuard
-is no longer needed! eduvpn-common currently also cleans up the running
-ProxyGuard process in `cleanup`.
-
-This function proxies WireGuard UDP connections over HTTP:
-https://codeberg.org/eduvpn/proxyguard. These input variables can be gotten
-from the configuration that is retrieved using the `proxy` JSON key
-
-  - `c` is the cookie
-  - `listen` is the ip:port of the local udp connection, this is what is set
-    to the WireGuard endpoint
-  - `tcpsp` is the TCP source port
-  - `peer` is the ip:port of the remote server
+StartProxyguard starts the 'proxyguard' procedure in eduvpn-common.
+eduvpn-common currently also cleans up the running ProxyGuard process in
+`cleanup`. If the proxy cannot be started it returns an error.
+
+This function proxies WireGuard UDP connections over HTTP: [ProxyGuard on
+Codeberg](https://codeberg.org/eduvpn/proxyguard).
+
+These input variables can be gotten from the configuration that is retrieved
+using the `proxy` JSON key
+
+  - `c` is the cookie. Note that if you cancel/delete the cookie,
+    ProxyGuard gets cleaned up. Common automatically cleans up ProxyGuard
+    when `Cleanup` is called, but it is good to cleanup yourself too.
+  - `listen` is the `ip:port` of the local udp connection, this is what is
+    set to the WireGuard endpoint
+  - `tcpsp` is the TCP source port. Pass 0 if you do not route based on
+    source port, so far only the Linux client has to pass non-zero.
+  - `peer` is the `ip:port` of the remote server
   - `proxySetup` is a callback which is called when the socket is setting
     up, this can be used for configuring routing in the client. It takes
     two arguments: the file descriptor (integer) and a JSON list of IPs the
@@ -912,5 +915,8 @@ from the configuration that is retrieved using the `proxy` JSON key
     when the actual wireguard connection can be started. This callback
     returns and takes no arguments
 
-If the proxy cannot be started it returns an error
+Example Input: ```StartProxyGuard(myCookie, "127.0.0.1:1337", 0,
+"5.5.5.5:51820", proxySetupCB, proxyReadyCB)```
+
+Example Output: ```null```