[PATCH] libosmocore[master]: [doc] counter.[ch] Add Doxygen API documentation

Harald Welte gerrit-no-reply at lists.osmocom.org
Mon Oct 16 12:53:46 UTC 2017


Review at  https://gerrit.osmocom.org/4280

[doc] counter.[ch] Add Doxygen API documentation

This adds a more complete set of API documentation for all
osmo_counter relatedd functions and definitions.

Change-Id: I24283c05620ee86a8beb165af98a85d754549efb
---
M include/osmocom/core/counter.h
M src/counter.c
2 files changed, 23 insertions(+), 16 deletions(-)


  git pull ssh://gerrit.osmocom.org:29418/libosmocore refs/changes/80/4280/1

diff --git a/include/osmocom/core/counter.h b/include/osmocom/core/counter.h
index f4429cd..e692f7e 100644
--- a/include/osmocom/core/counter.h
+++ b/include/osmocom/core/counter.h
@@ -3,7 +3,7 @@
 /*! \file counter.h
  *  Common routines regarding counter handling */
 
-/*! structure representing a single counter */
+/*! Structure representing a single counter */
 struct osmo_counter {
 	struct llist_head list;		/*!< internal list head */
 	const char *name;		/*!< human-readable name */
@@ -12,13 +12,15 @@
 	unsigned long previous;		/*!< previous value */
 };
 
-/*! Decrement counter */
+/*! Decrement given counter by one
+ *  \param[in] ctr Counter that's to be decremented */
 static inline void osmo_counter_dec(struct osmo_counter *ctr)
 {
 	ctr->value--;
 }
 
-/*! Increment counter */
+/*! Increment counter by one.
+ *  \param[in] Counter that's to be incremented */
 static inline void osmo_counter_inc(struct osmo_counter *ctr)
 {
 	ctr->value++;
@@ -36,25 +38,12 @@
 	ctr->value = 0;
 }
 
-/*! Allocate a new counter */
 struct osmo_counter *osmo_counter_alloc(const char *name);
 
-/*! Free the specified counter
- *  \param[in] ctr Counter
- */
 void osmo_counter_free(struct osmo_counter *ctr);
 
-/*! Iterate over all counters
- *  \param[in] handle_counter Call-back function, aborts if rc < 0
- *  \param[in] data Private dtata handed through to \a handle_counter
- */
 int osmo_counters_for_each(int (*handle_counter)(struct osmo_counter *, void *), void *data);
 
-/*! Resolve counter by human-readable name
- *  \param[in] name human-readable name of counter
- *  \returns pointer to counter (\ref osmo_counter) or NULL otherwise
- */
 struct osmo_counter *osmo_counter_get_by_name(const char *name);
 
-/*! Return the counter difference since the last call to this function */
 int osmo_counter_difference(struct osmo_counter *ctr);
diff --git a/src/counter.c b/src/counter.c
index 6fa87ba..2963777 100644
--- a/src/counter.c
+++ b/src/counter.c
@@ -29,8 +29,12 @@
 
 static LLIST_HEAD(counters);
 
+/*! Global talloc context for all osmo_counter allocations. */
 void *tall_ctr_ctx;
 
+/*! Allocate a new counter with given name. Allocates from tall_ctr_ctx
+ *  \param[in] name Human-readable string name for the counter
+ *  \returns Allocated counter on success; NULL on error */
 struct osmo_counter *osmo_counter_alloc(const char *name)
 {
 	struct osmo_counter *ctr = talloc_zero(tall_ctr_ctx, struct osmo_counter);
@@ -44,12 +48,18 @@
 	return ctr;
 }
 
+/*! Release/Destroy a given counter
+ *  \param[in] ctr Counter to be destroyed */
 void osmo_counter_free(struct osmo_counter *ctr)
 {
 	llist_del(&ctr->list);
 	talloc_free(ctr);
 }
 
+/*! Iterate over all counters; call \a handle_cunter call-back for each.
+ *  \param[in] handle_counter Call-back to be called for each counter; aborts if rc < 0
+ *  \param[in] data Opaque data passed through to \a handle_counter function
+ *  \returns 0 if all \a handle_counter calls successfull; negative on error */
 int osmo_counters_for_each(int (*handle_counter)(struct osmo_counter *, void *),
 			   void *data)
 {
@@ -65,6 +75,9 @@
 	return rc;
 }
 
+/*! Find a counter by its name.
+ *  \param[in] name Name used to look-up/search counter
+ *  \returns Counter on success; NULL if not found */
 struct osmo_counter *osmo_counter_get_by_name(const char *name)
 {
 	struct osmo_counter *ctr;
@@ -76,6 +89,11 @@
 	return NULL;
 }
 
+/*! Compute difference between current and previous counter value.
+ *  \param[in] ctr Counter of which the difference is to be computed
+ *  \returns Delta value between current counter and previous counter. Please
+ *	     note that the actual counter values are unsigned long, while the
+ *	     difference is computed as signed integer! */
 int osmo_counter_difference(struct osmo_counter *ctr)
 {
 	int delta = ctr->value - ctr->previous;

-- 
To view, visit https://gerrit.osmocom.org/4280
To unsubscribe, visit https://gerrit.osmocom.org/settings

Gerrit-MessageType: newchange
Gerrit-Change-Id: I24283c05620ee86a8beb165af98a85d754549efb
Gerrit-PatchSet: 1
Gerrit-Project: libosmocore
Gerrit-Branch: master
Gerrit-Owner: Harald Welte <laforge at gnumonks.org>


More information about the gerrit-log mailing list