Skip to content

Commit 0118c8f

Browse files
committed
docs: document the members of the files this change touches that Doxygen flags
The Docs check fails a pull request on any Doxygen warning in a file it changes, old ones included (#132). This change touches e3_agent.hpp, e3_connector.hpp, subscription_manager.hpp, c_api.h and posix_connector.hpp, so their gaps are filled here instead of being left for the check to report. * @return and @PARAM for the accessors, setters and callbacks of E3Agent, E3Connector and SubscriptionManager; a one-line description for the handler type aliases, the move operations and the data members. * e3_config_t and e3_c_service_model_desc_t get a `///<` description for every member, in place of the `//` and `/* */` comments, which Doxygen does not read. The struct and the SM handle in c_api.cpp, E3Agent::Impl and DAppSession::Impl are described, as is each of their members. * A log path pattern written `<role>` is written without the angle brackets, which Doxygen read as an HTML tag. The integrator guide's line pointers follow the added comment lines. Comments only: no code changes. Assisted-by: Claude:claude-sonnet-5-5 Signed-off-by: Thecave3 <thecave003@gmail.com>
1 parent 7d83eb0 commit 0118c8f

9 files changed

Lines changed: 219 additions & 84 deletions

File tree

‎docs/e3ap/integrator-guide.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -84,7 +84,7 @@ in the connectors.
8484
| The dApp handles every MESSAGE ACK, with no dApp filter | `e3_interface.cpp:1812-1826` |
8585
| dApp report goes through a queue of 1024 and a worker | `e3_interface.cpp:687-717`, `800-821`, `1297-1305` |
8686
| A report with `sequence_id` 0 is refused with `INVALID_PARAM` | `e3_interface.cpp:1957` |
87-
| xApp control from the E3 Agent has no check of `sequence_id` | `src/core/e3_agent.cpp:230-251` |
87+
| xApp control from the E3 Agent has no check of `sequence_id` | `src/core/e3_agent.cpp:234-255` |
8888
| Release from the dApp: unregister, free identifiers, stop service models | `e3_interface.cpp:1307-1330`; `subscription_manager.cpp:84-138` |
8989
| RELEASE from the E3 Agent to a dApp that sent nothing for `dapp_idle_timeout_s` (default 1800 s, 0 is off): queued first, then the removal a release from the dApp gets. Only what the dApp sends resets the time | `e3_interface.cpp:1428-1448`; `subscription_manager.cpp:403-410`, `422-434` |
9090
| RELEASE from the E3 Agent: the dApp clears its session | `e3_interface.cpp:1665-1698` |
@@ -97,7 +97,7 @@ in the connectors.
9797

9898
| Claim | Code pointer |
9999
|---|---|
100-
| POSIX framing: 4 octets, network order, chunks of 8192 | `posix_connector.cpp:937-973`, `posix_connector.hpp:121` |
100+
| POSIX framing: 4 octets, network order, chunks of 8192 | `posix_connector.cpp:937-973`, `posix_connector.hpp:133` |
101101
| Framed receive refuses 0 and more than 65536 | `posix_connector.cpp:999` |
102102
| The dApp sends unframed | `posix_connector.cpp:681`, `798` |
103103
| The E3 Agent reads one raw `recv()` of up to 60000 octets | `posix_connector.cpp:355`, `537` |
@@ -129,7 +129,7 @@ Update the hex in `tests/test_asn1_golden.cpp` and add a row to the change ledge
129129
These comments disagree with the code. They are not discrepancies of the protocol.
130130

131131
* `include/libe3/types.hpp:538` says dApp identifiers are 1 to 100. The range is 1 to 65535.
132-
* `include/libe3/subscription_manager.hpp:114` says at most 101 dApps. `:148` says RAN function identifiers 0 to 255. `:34` and `:151` say that periodicity 0 means "the service model default".
132+
* `include/libe3/subscription_manager.hpp:115` says at most 101 dApps. `:148` says RAN function identifiers 0 to 255. `:34` and `:151` say that periodicity 0 means "the service model default".
133133
* `types.hpp:211` and `e3_encoder.hpp:81` use `0.0.0` as the version example. The default is `1.0.0`.
134134
* `types.hpp:442` and `include/libe3/c_api.h:166` leave Protobuf out of the encoding comments.
135135
* `include/libe3/e3_agent.hpp` says `register_sm` returns `STATE_ERROR` when the agent runs. It does not.

‎include/libe3/c_api.h‎

Lines changed: 32 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -80,15 +80,15 @@ e3_error_t e3_agent_set_dapp_status_changed_handler(
8080
* - Callbacks are invoked by the C++ adapter and receive `user_data`.
8181
*/
8282
typedef struct {
83-
const char* name; // Service Model name (null-terminated string)
84-
uint32_t version; // Service Model version
85-
uint32_t ran_function_id; // RAN function ID for this SM
83+
const char* name; ///< Service Model name (null-terminated string)
84+
uint32_t version; ///< Service Model version
85+
uint32_t ran_function_id; ///< RAN function ID for this SM
8686

87-
const uint32_t* telemetry_ids; // Array of supported telemetry IDs (copied by library)
88-
size_t telemetry_ids_len; // Number of telemetry IDs
87+
const uint32_t* telemetry_ids; ///< Array of supported telemetry IDs (copied by library)
88+
size_t telemetry_ids_len; ///< Number of telemetry IDs
8989

90-
const uint32_t* control_ids; // Array of supported control IDs (copied by library)
91-
size_t control_ids_len; // Number of control IDs
90+
const uint32_t* control_ids; ///< Array of supported control IDs (copied by library)
91+
size_t control_ids_len; ///< Number of control IDs
9292

9393
/* Opaque RAN function data (E3SM-encoded, advertised in the setup response).
9494
* Required, not optional: E3AP declares ranFunctionData as a mandatory
@@ -98,14 +98,14 @@ typedef struct {
9898
size_t ran_function_data_len; ///< Length in bytes; must be 1..32768
9999

100100
/* Callbacks */
101-
e3_sm_init_cb sm_init; // Called on SM registration
102-
e3_sm_destroy_cb sm_destroy; // Called on SM destruction
103-
e3_sm_start_cb sm_start; // Called when SM should start
104-
e3_sm_stop_cb sm_stop; // Called when SM should stop
105-
e3_sm_is_running_cb sm_is_running; // Called to query running state
106-
e3_sm_process_control_cb sm_process_control; // Called to process control actions
107-
108-
void* sm_context; // Opaque pointer passed to all callbacks
101+
e3_sm_init_cb sm_init; ///< Called on SM registration
102+
e3_sm_destroy_cb sm_destroy; ///< Called on SM destruction
103+
e3_sm_start_cb sm_start; ///< Called when SM should start
104+
e3_sm_stop_cb sm_stop; ///< Called when SM should stop
105+
e3_sm_is_running_cb sm_is_running; ///< Called to query running state
106+
e3_sm_process_control_cb sm_process_control; ///< Called to process control actions
107+
108+
void* sm_context; ///< Opaque pointer passed to all callbacks
109109
} e3_c_service_model_desc_t;
110110

111111
/* Create/destroy a C-backed ServiceModel */
@@ -167,25 +167,25 @@ e3_error_t e3_service_model_emit_message_ack(
167167
* Set `set_dapp_idle_timeout` to apply `dapp_idle_timeout_s`; a zeroed struct keeps the default.
168168
*/
169169
typedef struct {
170-
const char* ran_identifier;
171-
int link_layer; /* 0=ZMQ, 1=POSIX, -1=default */
172-
int transport_layer; /* 0=SCTP, 1=TCP, 2=IPC, -1=default */
173-
uint16_t setup_port;
174-
uint16_t subscriber_port;
175-
uint16_t publisher_port;
176-
const char* setup_endpoint;
177-
const char* subscriber_endpoint;
178-
const char* publisher_endpoint;
179-
int encoding; /* 0=ASN1, 1=JSON, 2=PROTOBUF, -1=default */
180-
size_t io_threads; /* 0=default */
181-
int log_level; /* -1=default */
182-
const char* log_path; /* NULL=auto (/tmp/e3_<role>[_<id>]_<euid>.log) */
170+
const char* ran_identifier; ///< RAN identifier; NULL keeps the default
171+
int link_layer; ///< 0=ZMQ, 1=POSIX, -1=default
172+
int transport_layer; ///< 0=SCTP, 1=TCP, 2=IPC, -1=default
173+
uint16_t setup_port; ///< Port of the setup channel (SCTP and TCP); 0 keeps the default
174+
uint16_t subscriber_port; ///< Port of the subscriber channel (SCTP and TCP); 0 keeps the default
175+
uint16_t publisher_port; ///< Port of the publisher channel (SCTP and TCP); 0 keeps the default
176+
const char* setup_endpoint; ///< Endpoint of the setup channel; NULL keeps the default
177+
const char* subscriber_endpoint; ///< Endpoint of the subscriber channel; NULL keeps the default
178+
const char* publisher_endpoint; ///< Endpoint of the publisher channel; NULL keeps the default
179+
int encoding; ///< 0=ASN1, 1=JSON, 2=PROTOBUF, -1=default
180+
size_t io_threads; ///< Number of I/O threads; 0=default
181+
int log_level; ///< Logging level; -1=default
182+
const char* log_path; ///< Log file; NULL=auto (`/tmp/e3_ROLE[_ID]_EUID.log`)
183183
/* A flag rather than a sentinel: core 0 is a legitimate target. */
184-
int pin_io_threads; /* 0=no pinning */
185-
int io_thread_affinity; /* logical core; Linux only, best-effort */
184+
int pin_io_threads; ///< Pin the I/O threads when non-zero; 0=no pinning
185+
int io_thread_affinity; ///< Logical core to pin to; Linux only, best-effort
186186
/* A flag too, because 0 is a legitimate timeout: it never removes a dApp. */
187-
int set_dapp_idle_timeout; /* 0=keep the library default (1800 s) */
188-
uint32_t dapp_idle_timeout_s; /* seconds without a message from a dApp before the RAN releases and removes it; 0=never */
187+
int set_dapp_idle_timeout; ///< Apply `dapp_idle_timeout_s` when non-zero; 0=keep the library default (1800 s)
188+
uint32_t dapp_idle_timeout_s; ///< Seconds without a message from a dApp before the RAN releases and removes it; 0=never
189189
} e3_config_t;
190190

191191
/**

‎include/libe3/e3_agent.hpp‎

Lines changed: 71 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -33,11 +33,17 @@ using DAppReportHandler = std::function<void(const DAppReport&)>;
3333
using DAppStatusChangedHandler = std::function<void()>;
3434

3535
// dApp-side handlers (used when role==DAPP).
36+
/** Callback for a SetupResponse (RAN → dApp). */
3637
using SetupResponseHandler = std::function<void(const SetupResponse&)>;
38+
/** Callback for a SubscriptionResponse (RAN → dApp). */
3739
using SubscriptionResponseHandler = std::function<void(const SubscriptionResponse&)>;
40+
/** Callback for an IndicationMessage (RAN → dApp). */
3841
using IndicationHandler = std::function<void(const IndicationMessage&)>;
42+
/** Callback for an XAppControlAction (xApp → dApp via the RAN). */
3943
using XAppControlHandler = std::function<void(const XAppControlAction&)>;
44+
/** Callback for a MessageAck (RAN → dApp). */
4045
using MessageAckHandler = std::function<void(const MessageAck&)>;
46+
/** Callback for the end of the dApp's session with the RAN, with the reason. */
4147
using DisconnectHandler = std::function<void(DisconnectReason)>;
4248

4349
/**
@@ -100,7 +106,12 @@ class E3Agent {
100106
// Non-copyable, movable
101107
E3Agent(const E3Agent&) = delete;
102108
E3Agent& operator=(const E3Agent&) = delete;
109+
/** @brief Move constructor. */
103110
E3Agent(E3Agent&&) noexcept;
111+
/**
112+
* @brief Move assignment.
113+
* @return This agent
114+
*/
104115
E3Agent& operator=(E3Agent&&) noexcept;
105116

106117
// =========================================================================
@@ -138,11 +149,13 @@ class E3Agent {
138149

139150
/**
140151
* @brief Get current agent state
152+
* @return The state the agent is in
141153
*/
142154
AgentState state() const noexcept;
143155

144156
/**
145157
* @brief Check if agent is running
158+
* @return true while the agent is running
146159
*/
147160
bool is_running() const noexcept;
148161

@@ -167,19 +180,22 @@ class E3Agent {
167180
* @brief Get available RAN function IDs
168181
*
169182
* Returns the RAN function IDs from all registered Service Models.
183+
* @return The RAN function IDs
170184
*/
171185
std::vector<uint32_t> get_available_ran_functions() const;
172186

173187
/**
174188
* @brief Set callback for incoming dApp reports (dApp → RAN).
175189
* Call before start(). When a dApp sends a DApp report, this callback is invoked.
190+
* @param handler Called with each dApp report
176191
*/
177192
void set_dapp_report_handler(DAppReportHandler handler);
178193

179194
/**
180195
* @brief Set callback for dApp status changes.
181196
* Called when a dApp connects, disconnects, subscribes, or unsubscribes.
182197
* Call before start().
198+
* @param handler Called after each change
183199
*/
184200
void set_dapp_status_changed_handler(DAppStatusChangedHandler handler);
185201

@@ -235,22 +251,38 @@ class E3Agent {
235251
// once init() runs.
236252
// =========================================================================
237253

238-
/** Set callback for incoming SetupResponse (RAN → dApp). */
254+
/**
255+
* Set callback for incoming SetupResponse (RAN → dApp).
256+
* @param handler Called on every setup, so also when the dApp registers again
257+
*/
239258
void set_setup_response_handler(SetupResponseHandler handler);
240-
/** Set callback for incoming SubscriptionResponse (RAN → dApp). */
259+
/**
260+
* Set callback for incoming SubscriptionResponse (RAN → dApp).
261+
* @param handler Called with each response
262+
*/
241263
void set_subscription_response_handler(SubscriptionResponseHandler handler);
242-
/** Set callback for incoming IndicationMessage (RAN → dApp). */
264+
/**
265+
* Set callback for incoming IndicationMessage (RAN → dApp).
266+
* @param handler Called with each indication
267+
*/
243268
void set_indication_handler(IndicationHandler handler);
244-
/** Set callback for incoming XAppControlAction (xApp → dApp via RAN). */
269+
/**
270+
* Set callback for incoming XAppControlAction (xApp → dApp via RAN).
271+
* @param handler Called with each control action
272+
*/
245273
void set_xapp_control_handler(XAppControlHandler handler);
246-
/** Set callback for incoming MessageAck (RAN → dApp). */
274+
/**
275+
* Set callback for incoming MessageAck (RAN → dApp).
276+
* @param handler Called with each acknowledgement
277+
*/
247278
void set_message_ack_handler(MessageAckHandler handler);
248279
/**
249280
* Set callback for the end of the dApp's session with the RAN: a release for
250281
* this dApp, or a closed or failed connection. Fires once, after dapp_id()
251282
* has been cleared. Unless E3Config::reconnect_interval_ms is 0 the dApp then
252283
* registers again by itself, with a new dapp_id() and no subscriptions: subscribe
253284
* again from the setup response handler. It does not after release() or stop().
285+
* @param handler Called once per ended session, with the reason
254286
*/
255287
void set_disconnect_handler(DisconnectHandler handler);
256288

@@ -260,16 +292,25 @@ class E3Agent {
260292
*/
261293
std::optional<uint32_t> dapp_id() const noexcept;
262294

263-
/** RAN functions this dApp is currently subscribed to. */
295+
/**
296+
* RAN functions this dApp is currently subscribed to.
297+
*
298+
* @return The RAN function IDs
299+
*/
264300
std::vector<uint32_t> subscribed_ran_functions() const;
265301

266-
/** Subscription IDs this dApp currently holds. */
302+
/**
303+
* Subscription IDs this dApp currently holds.
304+
*
305+
* @return The subscription IDs
306+
*/
267307
std::vector<uint32_t> active_subscription_ids() const;
268308

269309
/**
270310
* @brief Block until the dApp setup handshake completes.
271311
* @return SUCCESS on positive SetupResponse, CONNECTION_FAILED on negative,
272312
* TIMEOUT if the wait elapses, INVALID_PARAM on RAN-role.
313+
* @param timeout How long to wait at most
273314
*/
274315
ErrorCode wait_for_setup(std::chrono::milliseconds timeout);
275316

@@ -297,7 +338,12 @@ class E3Agent {
297338
std::optional<uint32_t> periodicity = std::nullopt,
298339
uint32_t* out_request_id = nullptr);
299340

300-
/** Send a SubscriptionDelete for a previously subscribed RAN function. */
341+
/**
342+
* Send a SubscriptionDelete for a previously subscribed RAN function.
343+
*
344+
* @param ran_function_id RAN function to unsubscribe from
345+
* @return ErrorCode::SUCCESS if the delete was queued, an error code otherwise
346+
*/
301347
ErrorCode unsubscribe(uint32_t ran_function_id);
302348

303349
/**
@@ -311,6 +357,7 @@ class E3Agent {
311357
* @param out_message_id when non-null, receives the assigned E3-MessageID on
312358
* success, so the caller can correlate a later ack/response back to
313359
* this send.
360+
* @return ErrorCode::SUCCESS if the control was queued, an error code otherwise
314361
*/
315362
ErrorCode send_control(uint32_t ran_function_id,
316363
uint32_t control_id,
@@ -328,17 +375,23 @@ class E3Agent {
328375
* @param out_message_id when non-null, receives the assigned E3-MessageID on
329376
* success, so the caller can correlate a later ack/response back to
330377
* this send.
378+
* @return ErrorCode::SUCCESS if the report was queued, an error code otherwise
331379
*/
332380
ErrorCode send_report(uint32_t ran_function_id,
333381
std::vector<uint8_t> report_data,
334382
uint32_t sequence_id,
335383
uint32_t* out_message_id = nullptr);
336384

337-
/** Send a ReleaseMessage. The dApp stays running until stop() is called. */
385+
/**
386+
* Send a ReleaseMessage. The dApp stays running until stop() is called.
387+
*
388+
* @return ErrorCode::SUCCESS if the release was queued, an error code otherwise
389+
*/
338390
ErrorCode release();
339391

340392
/**
341393
* @brief Get list of registered dApp IDs
394+
* @return The dApp IDs
342395
*/
343396
std::vector<uint32_t> get_registered_dapps() const;
344397

@@ -375,6 +428,8 @@ class E3Agent {
375428
* @brief Get the reporting periodicity a dApp requested for a RAN function
376429
*
377430
* @return periodicity in microseconds, 0 if not set or subscription not found
431+
* @param dapp_id The dApp
432+
* @param ran_function_id The RAN function
378433
*/
379434
uint32_t get_subscription_periodicity(
380435
uint32_t dapp_id, uint32_t ran_function_id
@@ -384,6 +439,8 @@ class E3Agent {
384439
* @brief Get the telemetry IDs a dApp requested for a RAN function
385440
*
386441
* @return vector of telemetry IDs (empty if none requested or subscription not found)
442+
* @param dapp_id The dApp
443+
* @param ran_function_id The RAN function
387444
*/
388445
std::vector<uint32_t> get_subscription_telemetry_ids(
389446
uint32_t dapp_id, uint32_t ran_function_id
@@ -393,6 +450,8 @@ class E3Agent {
393450
* @brief Get the control IDs a dApp requested for a RAN function
394451
*
395452
* @return vector of control IDs (empty if none requested or subscription not found)
453+
* @param dapp_id The dApp
454+
* @param ran_function_id The RAN function
396455
*/
397456
std::vector<uint32_t> get_subscription_control_ids(
398457
uint32_t dapp_id, uint32_t ran_function_id
@@ -404,6 +463,7 @@ class E3Agent {
404463

405464
/**
406465
* @brief Get current configuration
466+
* @return The configuration the agent was created with
407467
*/
408468
const E3Config& config() const noexcept;
409469

@@ -413,11 +473,13 @@ class E3Agent {
413473

414474
/**
415475
* @brief Get number of registered dApps
476+
* @return The number of dApps
416477
*/
417478
size_t dapp_count() const;
418479

419480
/**
420481
* @brief Get total number of active subscriptions
482+
* @return The number of subscriptions
421483
*/
422484
size_t subscription_count() const;
423485

0 commit comments

Comments
 (0)