mavsdk_server: document and fixup C API

This adds docstrings to the D API and changes the return value of
mavsdk_server_run as you would expect a C API, wich 0 being successful.

examples/start_stop_server/start_stop_server.cpp

@@ -34,7 +34,12 @@ int main(int argc, char* argv[])
     mavsdk_server_init(&mavsdk_server);
 
     // This returns when a system has been discovered.
-    mavsdk_server_run(mavsdk_server, argv[1], 50051);
+    int ret = mavsdk_server_run(mavsdk_server, argv[1], 50051);
+    if (ret != 0) {
+        std::cout << "mavsdk_server_run failed: " << ret << std::endl;
+        mavsdk_server_destroy(mavsdk_server);
+        return ret;
+    }
 
     while (!_should_stop.load()) {
         std::this_thread::sleep_for(std::chrono::seconds(1));

src/mavsdk_server/src/mavsdk_server_api.cpp

@@ -12,16 +12,16 @@ int mavsdk_server_run(
 {
     if (!mavsdk_server->connect(std::string(system_address))) {
         // Connection was cancelled
-        return false;
+        return 1;
     }
 
     auto grpc_port = mavsdk_server->startGrpcServer(mavsdk_server_port);
     if (grpc_port == 0) {
         // Server failed to start
-        return false;
+        return 2;
     }
 
-    return true;
+    return 0;
 }
 
 int mavsdk_server_run_with_mavlink_ids(

src/mavsdk_server/src/mavsdk_server_api.h

@@ -18,24 +18,71 @@ extern "C" {
 
 struct MavsdkServer;
 
+/*
+ * Allocate and initialize MavsdkServer struct.
+ *
+ * @param mavsdk_server Pointer to pointer to MavsdkServer.
+ */
 DLLExport void mavsdk_server_init(struct MavsdkServer** mavsdk_server);
 
+/*
+ * Run MavsdkServer.
+ *
+ * @param mavsdk_server Pointer to initialized MavsdkServer
+ * @param system_address Connection string for MAVLink as used by add_any_connection
+ * @param mavsdk_server_port gRPC server port
+ * @return 0 if successful
+ */
 DLLExport int mavsdk_server_run(
     struct MavsdkServer* mavsdk_server, const char* system_address, const int mavsdk_server_port);
 
+/*
+ * Run MavsdkServer.
+ *
+ * Note: This function immediately returns. To wait until the server exits,
+ *       use mavsdk_server_attach.
+ *
+ * @param mavsdk_server Pointer to initialized MavsdkServer
+ * @param system_address Connection string for MAVLink as used by add_any_connection
+ * @param mavsdk_server_port gRPC server port
+ * @param system_id MAVLink system ID for MAVSDK
+ * @param component_id MAVLink component ID for MAVSDK
+ * @return 0 if successful
+ */
 DLLExport int mavsdk_server_run_with_mavlink_ids(
     struct MavsdkServer* mavsdk_server,
     const char* system_address,
     const int mavsdk_server_port,
     const uint8_t system_id,
     const uint8_t component_id);
 
+/*
+ * Get gRPC port.
+ *
+ * @param mavsdk_server Pointer to initialized MavsdkServer
+ * @return gRPC port used
+ */
 DLLExport int mavsdk_server_get_port(struct MavsdkServer* mavsdk_server);
 
+/*
+ * Attach to MavsdkServer. This only returns once the server is stopped.
+ *
+ * @param mavsdk_server Pointer to initialized MavsdkServer
+ */
 DLLExport void mavsdk_server_attach(struct MavsdkServer* mavsdk_server);
 
+/*
+ * Stop MavsdkServer.
+ *
+ * @param mavsdk_server Pointer to initialized MavsdkServer
+ */
 DLLExport void mavsdk_server_stop(struct MavsdkServer* mavsdk_server);
 
+/*
+ * Clean up MavsdkServer object. Counter part to mavsdk_server_init.
+ *
+ * @param mavsdk_server Pointer to initialized MavsdkServer
+ */
 DLLExport void mavsdk_server_destroy(struct MavsdkServer* mavsdk_server);
 
 #ifdef __cplusplus

src/mavsdk_server/src/mavsdk_server_bin.cpp

@@ -88,17 +88,17 @@ int main(int argc, char** argv)
 
     MavsdkServer* mavsdk_server;
     mavsdk_server_init(&mavsdk_server);
-    const auto is_started = mavsdk_server_run_with_mavlink_ids(
+    const int ret = mavsdk_server_run_with_mavlink_ids(
         mavsdk_server,
         connection_url.c_str(),
         mavsdk_server_port,
         static_cast<uint8_t>(mavsdk_sysid),
         static_cast<uint8_t>(mavsdk_compid));
 
-    if (!is_started) {
+    if (ret != 0) {
         std::cout << "Failed to start, exiting...\n";
         mavsdk_server_destroy(mavsdk_server);
-        return 1;
+        return ret;
     }
 
     mavsdk_server_attach(mavsdk_server);