From 0268ed5910a27a11dc4a5da2acee7b09b6615131 Mon Sep 17 00:00:00 2001
From: Julian Oes <julian@oes.ch>
Date: Sun, 26 Jan 2025 09:26:29 +1100
Subject: [PATCH] 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.
---
 .../start_stop_server/start_stop_server.cpp   |  7 ++-
 src/mavsdk_server/src/mavsdk_server_api.cpp   |  6 +--
 src/mavsdk_server/src/mavsdk_server_api.h     | 47 +++++++++++++++++++
 src/mavsdk_server/src/mavsdk_server_bin.cpp   |  6 +--
 4 files changed, 59 insertions(+), 7 deletions(-)

diff --git a/examples/start_stop_server/start_stop_server.cpp b/examples/start_stop_server/start_stop_server.cpp
index ce692625fc..d11d2776f5 100644
--- a/examples/start_stop_server/start_stop_server.cpp
+++ b/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));
diff --git a/src/mavsdk_server/src/mavsdk_server_api.cpp b/src/mavsdk_server/src/mavsdk_server_api.cpp
index 5cd3ba9ce2..f86d5d71b2 100644
--- a/src/mavsdk_server/src/mavsdk_server_api.cpp
+++ b/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(
diff --git a/src/mavsdk_server/src/mavsdk_server_api.h b/src/mavsdk_server/src/mavsdk_server_api.h
index 11c2c75aa3..2a98175bd6 100644
--- a/src/mavsdk_server/src/mavsdk_server_api.h
+++ b/src/mavsdk_server/src/mavsdk_server_api.h
@@ -18,11 +18,37 @@ 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,
@@ -30,12 +56,33 @@ DLLExport int mavsdk_server_run_with_mavlink_ids(
     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
diff --git a/src/mavsdk_server/src/mavsdk_server_bin.cpp b/src/mavsdk_server/src/mavsdk_server_bin.cpp
index 29bb74728c..8bb42e264e 100644
--- a/src/mavsdk_server/src/mavsdk_server_bin.cpp
+++ b/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);