Add C++ library docs

cpp/README.md

+# Vereign C++ Client Library
+
+## Overview
+
+TODO
+
+## Build
+
+The project uses git submodules for the gRPC protobuf definitions.
+
+So after cloning run `git submodule update --init`.
+
+The protobuf definitions and the generated C++ gRPC client/server are located in
+[https://code.vereign.com/code/vcl-proto](https://code.vereign.com/code/vcl-proto) project and 
+are added as submodule at `proto` subdir.
+
+### Windows
+
+You need Visual Studio 2019 or alternatively install just the build tools and c++ compiler - go to
+[https://visualstudio.microsoft.com/downloads/](https://visualstudio.microsoft.com/downloads/)
+then scroll and open `Tools for Visual Studio 2019` and download/install `Visual Studio Build Tools 2019`.
+The 2019 build tools include cmake, and currently it is 3.16.19112601-MSVC_2.
+They also include Ninja build tool.
+
+**NOTE: Currently only builds with Ninja are tested under Windows**
+
+#### Build the third party dependencies
+
+Go to the `vcl/cpp` directory.
+
+First configure the cmake build.
+Open `x64 Native Tools Command Prompt` it is preconfigured with all the needed tools including cmake
+and ninja.
+
+```shell
+> mkdir cmake-build-vendor-debug
+> cd cmake-build-vendor-debug
+> cmake -G Ninja -DCMAKE_BUILD_TYPE=Debug ../vendor
+```
+
+Next build the dependencies.
+Note that this will take a while, and that it could be slowed a lot by the windows defender.
+You can configure the windows defender to the project directory.
+
+```shell
+> ninja
+```
+
+#### Build the vereign library
+
+Go to the `vcl/cpp` directory.
+
+```
+> mkdir cmake-build-debug
+> cd cmake-build-debug
+> cmake -G Ninja -DCMAKE_BUILD_TYPE=Debug ..
+> ninja vereign -v
+```
+
+The `vereign.dll` will be created inside `cmake-build-debug\bin\Debug` directory.
+
+### C API Usage
+
+For C/C++ users, the library has a single header file located in `include\vereign` directory.
+
+The service is started with `vereign_service_start`. This will start a gRPC server in its own thread(s).
+The call returns immediately.
+
+After the service is started you can use your favorite language generated gRPC client to communicate
+with the service.
+
+Use the `vereign_service_selected_port` function to get the listen port of the gRPC server.
+
+When you are finished with the service, for example upon shutdown of the application, one must use
+the `vereign_service_shutdown` API. It will shutdown the service and free any acquired resources.
+Afterwards the returned `vereign_service` pointer from the start call is invalid and must not be used anymore.
+
+For more detailed info check the source code documentation in the header
+[include/vereign/vereign.h](cpp/include/vereign/vereign.h).
+You can also look at C++ usage example in the C API integration test
+[tests/integration/integration_test.cc](cpp/tests/integration/integration_test.cc).
+
+The gRPC APIs are located here [https://code.vereign.com/code/vcl-proto/-/tree/master/proto%2Fvereign%2Fclient_library](https://code.vereign.com/code/vcl-proto/-/tree/master/proto%2Fvereign%2Fclient_library).
+
+
+TODO: Add more documentation/reference; instructions to generate doxygen reference.

cpp/include/vereign/vereign.h

@@ -57,7 +57,9 @@ typedef struct vereign_service vereign_service;
  *
  * The returned ::vereign_service object must be destroyed with ::vereign_service_shutdown method.
  * After successful start, the gRPC bind port can be retrieved with the
- * ::vereign_service_selected_port method.
+ * ::vereign_service_selected_port method. This is useful if the `listen_address` is in the form
+ * "<host>:" (for example "localhost:"), in which case the port is not provided by the user but
+ * from the OS.
  *
  * When the gRPC server cannot bind, `err` will have code VEREIGN_ERR_GRPC_BIND_FAILED.
  * Any other failures will set `err` with code VEREIGN_ERR_INTERNAL.