Skip to content

Commit df6a666

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 sm_interface.hpp and swig/e3_dapp_session.hpp, so their gaps are filled here instead of being left for the check to report. * @return and @PARAM for the accessors, the registry functions and the protected helpers of ServiceModel and SmRegistry. * @PARAM and @return for the setup accessors, unsubscribe, poll_events and dropped_events of DAppSession. The integrator guide's pointer to granted_periodicity() follows the added lines. Comments only: no code changes. Assisted-by: Claude:claude-sonnet-5-5 Signed-off-by: Thecave3 <thecave003@gmail.com>
1 parent a372a3e commit df6a666

3 files changed

Lines changed: 49 additions & 12 deletions

File tree

‎docs/e3ap/integrator-guide.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -74,7 +74,7 @@ in the connectors.
7474
| A negative response still gives "success" to the dApp | `e3_interface.cpp:1553`, `1726-1729` |
7575
| Subscription: the registration, the RAN function, the lists and every identifier are checked, and a refusal carries a cause | `e3_interface.cpp:928-961`, `1117-1210` |
7676
| Repeat returns the existing identifier. Renewal after expiry keeps the identifier | `subscription_manager.cpp:187-205` |
77-
| The response lists the request lists for a new subscription and the lists the E3 Agent holds for a repeat. Its interval is the one the service model reports with `granted_periodicity()`, and none when it reports 0, nothing, or more than 60000000 | `e3_interface.cpp:1158-1161`, `1181-1201`; `sm_interface.hpp:92-108` |
77+
| The response lists the request lists for a new subscription and the lists the E3 Agent holds for a repeat. Its interval is the one the service model reports with `granted_periodicity()`, and none when it reports 0, nothing, or more than 60000000 | `e3_interface.cpp:1158-1161`, `1181-1201`; `sm_interface.hpp:97-113` |
7878
| Subscription expiry sweep every 250 ms | `e3_interface.cpp:40`, `825-849` |
7979
| Subscription delete | `e3_interface.cpp:1212-1253` |
8080
| The dApp keeps its own deadline from the response | `e3_interface.cpp:1767-1777` |

‎include/libe3/sm_interface.hpp‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,26 +45,31 @@ class ServiceModel {
4545

4646
/**
4747
* @brief Get SM name
48+
* @return The name of the SM
4849
*/
4950
virtual std::string name() const = 0;
5051

5152
/**
5253
* @brief Get SM version
54+
* @return The version number of the SM
5355
*/
5456
virtual uint32_t version() const = 0;
5557

5658
/**
5759
* @brief Get RAN function ID for this SM
60+
* @return The RAN function this SM serves
5861
*/
5962
virtual uint32_t ran_function_id() const = 0;
6063

6164
/**
6265
* @brief Get telemetry IDs supported by this SM
66+
* @return The telemetry identifiers the SM supports
6367
*/
6468
virtual std::vector<uint32_t> telemetry_ids() const = 0;
6569

6670
/**
6771
* @brief Get control IDs supported by this SM
72+
* @return The control identifiers the SM supports
6873
*/
6974
virtual std::vector<uint32_t> control_ids() const = 0;
7075

@@ -139,6 +144,7 @@ class ServiceModel {
139144

140145
/**
141146
* @brief Check if SM is currently running
147+
* @return True while the SM is processing
142148
*/
143149
virtual bool is_running() const = 0;
144150

@@ -148,6 +154,9 @@ class ServiceModel {
148154
* Called by the E3 interface when a DAppControlAction is received for this
149155
* service model. Implementations can emit outbound PDUs (e.g. MessageAck,
150156
* IndicationMessage) via emit_outbound().
157+
* @param request_message_id Message identifier of the DAppControlAction
158+
* @param action The control action
159+
* @return ErrorCode::SUCCESS if the SM took the action
151160
*/
152161
virtual ErrorCode handle_control_action(
153162
uint32_t request_message_id,
@@ -162,6 +171,9 @@ class ServiceModel {
162171
*
163172
* This helper only builds the PDU. Implementations can decide whether to
164173
* emit it with emit_outbound() or suppress it when protocol semantics allow.
174+
* @param request_message_id Message identifier of the message acknowledged
175+
* @param response_code Result to report
176+
* @return The PDU
165177
*/
166178
static Pdu make_message_ack_pdu(
167179
uint32_t request_message_id,
@@ -180,6 +192,10 @@ class ServiceModel {
180192
*
181193
* This helper only builds the PDU. Implementations can emit it with
182194
* emit_outbound() when appropriate.
195+
* @param dapp_id dApp the indication is for
196+
* @param ran_function_id RAN function the indication comes from
197+
* @param protocol_data Opaque payload of the SM
198+
* @return The PDU
183199
*/
184200
static Pdu make_indication_pdu(
185201
uint32_t dapp_id,
@@ -197,6 +213,8 @@ class ServiceModel {
197213

198214
/**
199215
* @brief Emit an outbound PDU produced by the SM.
216+
* @param pdu The PDU to send
217+
* @return ErrorCode::SUCCESS if it was queued, ErrorCode::NOT_INITIALIZED if no emitter is set
200218
*/
201219
ErrorCode emit_outbound(Pdu&& pdu) {
202220
if (!outbound_emitter_) {
@@ -207,6 +225,7 @@ class ServiceModel {
207225

208226
/**
209227
* @brief Get currently subscribed dApps for this SM's RAN function.
228+
* @return The identifiers of the subscribed dApps, empty when no provider is set
210229
*/
211230
std::vector<uint32_t> get_subscribers() const {
212231
if (!subscribers_provider_) {
@@ -217,13 +236,15 @@ class ServiceModel {
217236

218237
/**
219238
* @brief Set the outbound PDU emitter callback (used by E3Interface).
239+
* @param emitter Callback that queues a PDU
220240
*/
221241
void set_outbound_emitter(std::function<ErrorCode(Pdu&&)> emitter) {
222242
outbound_emitter_ = std::move(emitter);
223243
}
224244

225245
/**
226246
* @brief Set subscriber provider callback (used by E3Interface).
247+
* @param provider Callback that lists the subscribed dApps
227248
*/
228249
void set_subscribers_provider(std::function<std::vector<uint32_t>()> provider) {
229250
subscribers_provider_ = std::move(provider);
@@ -251,6 +272,7 @@ class SmRegistry {
251272
public:
252273
/**
253274
* @brief Get the singleton instance
275+
* @return The registry
254276
*/
255277
static SmRegistry& instance();
256278

@@ -269,11 +291,16 @@ class SmRegistry {
269291
* @brief Register a Service Model factory
270292
*
271293
* Use this to defer SM creation until needed.
294+
* @param ran_function_id RAN function the factory serves
295+
* @param factory Creates the SM
296+
* @return ErrorCode::SUCCESS on success
272297
*/
273298
ErrorCode register_sm_factory(uint32_t ran_function_id, SmFactory factory);
274299

275300
/**
276301
* @brief Unregister a Service Model by RAN function ID
302+
* @param ran_function_id RAN function of the SM to remove
303+
* @return ErrorCode::SUCCESS on success, an error code otherwise
277304
*/
278305
ErrorCode unregister_sm(uint32_t ran_function_id);
279306

@@ -287,21 +314,28 @@ class SmRegistry {
287314

288315
/**
289316
* @brief Get all available RAN function IDs
317+
* @return The RAN functions that have an SM or a factory
290318
*/
291319
std::vector<uint32_t> get_available_ran_functions() const;
292320

293321
/**
294322
* @brief Start SM for a RAN function
323+
* @param ran_function_id RAN function whose SM is started
324+
* @return ErrorCode::SUCCESS on success, an error code otherwise
295325
*/
296326
ErrorCode start_sm(uint32_t ran_function_id);
297327

298328
/**
299329
* @brief Stop SM for a RAN function
330+
* @param ran_function_id RAN function whose SM is stopped
331+
* @return ErrorCode::SUCCESS on success, an error code otherwise
300332
*/
301333
ErrorCode stop_sm(uint32_t ran_function_id);
302334

303335
/**
304336
* @brief Check if SM is running
337+
* @param ran_function_id RAN function whose SM is asked about
338+
* @return True if its SM is running
305339
*/
306340
bool is_sm_running(uint32_t ran_function_id) const;
307341

‎swig/e3_dapp_session.hpp‎

Lines changed: 14 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -126,7 +126,7 @@ class DAppSession {
126126
/** @brief Start the agent, re-arming the inbound ring so a stop()->start()
127127
* cycle works again. @return ErrorCode as int. */
128128
int start();
129-
/** @brief Block until the setup handshake completes. @return ErrorCode as int. */
129+
/** @brief Block until the setup handshake completes. @param timeout_ms longest wait, in milliseconds. @return ErrorCode as int. */
130130
int wait_for_setup(int timeout_ms);
131131
/** @brief Send a ReleaseMessage (session keeps running until @ref stop). @return ErrorCode as int. */
132132
int release();
@@ -135,22 +135,22 @@ class DAppSession {
135135
* via @ref start. */
136136
void stop();
137137

138-
/** @brief dApp id assigned at setup, or -1 if not yet assigned. */
138+
/** @brief dApp id assigned at setup. @return the id, or -1 if not yet assigned. */
139139
long dapp_id() const;
140-
/** @brief RAN identifier from the SetupResponse, or "" if none. */
140+
/** @brief RAN identifier from the SetupResponse. @return the identifier, or "" if none. */
141141
std::string ran_identifier() const;
142142

143-
/** @brief SetupResponse code: 0=positive, 1=negative, -1=not received. */
143+
/** @brief SetupResponse code. @return 0=positive, 1=negative, -1=not received. */
144144
int setup_response_code() const;
145-
/** @brief Number of RAN functions advertised in the SetupResponse. */
145+
/** @brief Number of RAN functions advertised in the SetupResponse. @return the count. */
146146
std::size_t setup_ran_function_count() const;
147-
/** @brief RAN function id of advertised entry @p i (0 if out of range). */
147+
/** @brief RAN function id of an advertised entry. @param i index of the entry. @return the id, 0 if out of range. */
148148
uint32_t setup_ran_function_id(std::size_t i) const;
149-
/** @brief Telemetry ids of advertised entry @p i. */
149+
/** @brief Telemetry ids of an advertised entry. @param i index of the entry. @return the ids. */
150150
std::vector<uint32_t> setup_ran_function_telemetry(std::size_t i) const;
151-
/** @brief Control ids of advertised entry @p i. */
151+
/** @brief Control ids of an advertised entry. @param i index of the entry. @return the ids. */
152152
std::vector<uint32_t> setup_ran_function_control(std::size_t i) const;
153-
/** @brief Opaque ranFunctionData bytes of advertised entry @p i. */
153+
/** @brief Opaque ranFunctionData bytes of an advertised entry. @param i index of the entry. @return the bytes. */
154154
std::vector<uint8_t> setup_ran_function_data(std::size_t i) const;
155155

156156
/**
@@ -172,7 +172,7 @@ class DAppSession {
172172
std::vector<uint32_t> control_ids,
173173
int sub_time_ms,
174174
int periodicity);
175-
/** @brief Delete a previously created subscription. @return ErrorCode as int. */
175+
/** @brief Delete a previously created subscription. @param ran_function_id RAN function it was for. @return ErrorCode as int. */
176176
int unsubscribe(uint32_t ran_function_id);
177177

178178
/**
@@ -216,10 +216,13 @@ class DAppSession {
216216
* @p timeout_ms <= 0 polls non-blocking (does not busy-wait). Returns an
217217
* empty vector on a quiet tick or after @ref stop. The SWIG wrapper releases
218218
* the GIL for the whole call so libe3's threads run freely while Python waits.
219+
* @param max_batch most events to return
220+
* @param timeout_ms longest wait for the first event, in milliseconds
221+
* @return the events, empty on a quiet tick or after stop
219222
*/
220223
std::vector<E3Event> poll_events(std::size_t max_batch, int timeout_ms);
221224

222-
/** @brief Total inbound events dropped due to ring overflow (backpressure). */
225+
/** @brief Total inbound events dropped due to ring overflow (backpressure). @return the count. */
223226
unsigned long long dropped_events() const;
224227

225228
private:

0 commit comments

Comments
 (0)