[PATCH] Doxygen tweaks: fixed a lot of typos and minor errors (amended)

14 Feb 2013

diff --git a/Doxyfile.codec.in b/Doxyfile.codec.in
index 1b0df5e..4f539c7 100644
--- a/Doxyfile.codec.in
+++ b/Doxyfile.codec.in
@@ -688,7 +688,7 @@ EXAMPLE_RECURSIVE      = NO
 # directories that contain image that are included in the documentation (see
 # the \image command).

-IMAGE_PATH             = images/
+# IMAGE_PATH             = images/

 # The INPUT_FILTER tag can be used to specify a program that doxygen should
 # invoke to filter for each input file. Doxygen will invoke the filter program
@@ -1406,7 +1406,7 @@ PERLMOD_MAKEVAR_PREFIX =
 # evaluate all C-preprocessor directives found in the sources and include
 # files.

-ENABLE_PREPROCESSING   = NO
+ENABLE_PREPROCESSING   = YES

 # If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro
 # names in the source code. If set to NO (the default) only conditional
diff --git a/Doxyfile.core.in b/Doxyfile.core.in
index 4baa3d5..71843cc 100644
--- a/Doxyfile.core.in
+++ b/Doxyfile.core.in
@@ -688,7 +688,7 @@ EXAMPLE_RECURSIVE      = NO
 # directories that contain image that are included in the documentation (see
 # the \image command).

-IMAGE_PATH             = images/
+# IMAGE_PATH             = images/

 # The INPUT_FILTER tag can be used to specify a program that doxygen should
 # invoke to filter for each input file. Doxygen will invoke the filter program
@@ -1406,7 +1406,7 @@ PERLMOD_MAKEVAR_PREFIX =
 # evaluate all C-preprocessor directives found in the sources and include
 # files.

-ENABLE_PREPROCESSING   = NO
+ENABLE_PREPROCESSING   = YES

 # If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro
 # names in the source code. If set to NO (the default) only conditional
diff --git a/Doxyfile.gsm.in b/Doxyfile.gsm.in
index 36a6ae2..c4a837f 100644
--- a/Doxyfile.gsm.in
+++ b/Doxyfile.gsm.in
@@ -688,7 +688,7 @@ EXAMPLE_RECURSIVE      = NO
 # directories that contain image that are included in the documentation (see
 # the \image command).

-IMAGE_PATH             = images/
+# IMAGE_PATH             = images/

 # The INPUT_FILTER tag can be used to specify a program that doxygen should
 # invoke to filter for each input file. Doxygen will invoke the filter program
@@ -1406,7 +1406,7 @@ PERLMOD_MAKEVAR_PREFIX =
 # evaluate all C-preprocessor directives found in the sources and include
 # files.

-ENABLE_PREPROCESSING   = NO
+ENABLE_PREPROCESSING   = YES

 # If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro
 # names in the source code. If set to NO (the default) only conditional
diff --git a/Doxyfile.vty.in b/Doxyfile.vty.in
index 527cdb2..5f7a158 100644
--- a/Doxyfile.vty.in
+++ b/Doxyfile.vty.in
@@ -688,7 +688,7 @@ EXAMPLE_RECURSIVE      = NO
 # directories that contain image that are included in the documentation (see
 # the \image command).

-IMAGE_PATH             = images/
+# IMAGE_PATH             = images/

 # The INPUT_FILTER tag can be used to specify a program that doxygen should
 # invoke to filter for each input file. Doxygen will invoke the filter program
@@ -1406,7 +1406,7 @@ PERLMOD_MAKEVAR_PREFIX =
 # evaluate all C-preprocessor directives found in the sources and include
 # files.

-ENABLE_PREPROCESSING   = NO
+ENABLE_PREPROCESSING   = YES

 # If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro
 # names in the source code. If set to NO (the default) only conditional
diff --git a/include/osmocom/core/conv.h b/include/osmocom/core/conv.h
index e5b2a97..4cc791f 100644
--- a/include/osmocom/core/conv.h
+++ b/include/osmocom/core/conv.h
@@ -25,7 +25,7 @@
  */

 /*! \file conv.h
- *  \file Osmocom convolutional encoder and decoder
+ * Osmocom convolutional encoder and decoder
  */

 #ifndef __OSMO_CONV_H__
diff --git a/include/osmocom/core/crcXXgen.h.tpl
b/include/osmocom/core/crcXXgen.h.tpl
index 89d083a..a931bc3 100644
--- a/include/osmocom/core/crcXXgen.h.tpl
+++ b/include/osmocom/core/crcXXgen.h.tpl
@@ -28,7 +28,7 @@
  */

 /*! \file crcXXgen.h
- *  \file Osmocom generic CRC routines (for max XX bits poly) header
+ * Osmocom generic CRC routines (for max XX bits poly) header
  */


diff --git a/include/osmocom/core/crcgen.h b/include/osmocom/core/crcgen.h
index 8e208a7..69cef04 100644
--- a/include/osmocom/core/crcgen.h
+++ b/include/osmocom/core/crcgen.h
@@ -28,7 +28,7 @@
  */

 /*! \file crcgen.h
- *  \file Osmocom generic CRC routines global header
+ * Osmocom generic CRC routines global header
  */

 #include <osmocom/core/crc8gen.h>
diff --git a/include/osmocom/core/gsmtap_util.h
b/include/osmocom/core/gsmtap_util.h
index 5609381..eaa32a0 100644
--- a/include/osmocom/core/gsmtap_util.h
+++ b/include/osmocom/core/gsmtap_util.h
@@ -54,4 +54,6 @@ int gsmtap_send(struct gsmtap_inst *gti, uint16_t
arfcn, uint8_t ts,
 		int8_t signal_dbm, uint8_t snr, const uint8_t *data,
 		unsigned int len);

+/*! @} */
+
 #endif /* _GSMTAP_UTIL_H */
diff --git a/include/osmocom/core/logging.h b/include/osmocom/core/logging.h
index dc55d37..19f35b2 100644
--- a/include/osmocom/core/logging.h
+++ b/include/osmocom/core/logging.h
@@ -163,7 +163,7 @@ struct log_target {

 	/*! \brief call-back function to be called when the logging framework
 	 *	   wants to log somethnig.
-	 *  \param[[in] target logging target
+	 *  \param[in] target logging target
 	 *  \param[in] level log level of currnet message
 	 *  \param[in] string the string that is to be written to the log
 	 */
diff --git a/include/osmocom/core/msgb.h b/include/osmocom/core/msgb.h
index a1939ab..fe2733b 100644
--- a/include/osmocom/core/msgb.h
+++ b/include/osmocom/core/msgb.h
@@ -361,7 +361,7 @@ static inline int msgb_trim(struct msgb *msg, int len)
 }

 /*! \brief Trim the msgb to a given layer3 length
- *  \pram[in] msg message buffer
+ *  \param[in] msg message buffer
  *  \param[in] l3len new layer3 length
  *  \returns 0 in case of success, negative in case of error
  */
diff --git a/include/osmocom/core/prim.h b/include/osmocom/core/prim.h
index b1026fe..f61d808 100644
--- a/include/osmocom/core/prim.h
+++ b/include/osmocom/core/prim.h
@@ -5,7 +5,7 @@
  *  @{
  */

-/*! \file prim.c */
+/*! \file prim.h */

 #include <stdint.h>
 #include <osmocom/core/msgb.h>
@@ -37,7 +37,7 @@ struct osmo_prim_hdr {
 /*! \brief initialize a primitive header
  *  \param[in,out] oph primitive header
  *  \param[in] sap Service Access Point
- *  \param[in] primtive Primitive Number
+ *  \param[in] primitive Primitive Number
  *  \param[in] operation Primitive Operation (REQ/RESP/IND/CONF)
  *  \param[in] msg Message
  */
@@ -55,4 +55,6 @@ osmo_prim_init(struct osmo_prim_hdr *oph, unsigned int sap,
 /*! \brief primitive handler callback type */
 typedef int (*osmo_prim_cb)(struct osmo_prim_hdr *oph, void *ctx);

+/*! @} */
+
 #endif /* OSMO_PRIMITIVE_H */
diff --git a/include/osmocom/core/serial.h b/include/osmocom/core/serial.h
index 889bd8a..1640a6d 100644
--- a/include/osmocom/core/serial.h
+++ b/include/osmocom/core/serial.h
@@ -25,7 +25,7 @@
  */

 /*! \file serial.h
- *  \file Osmocom serial port helpers
+ * Osmocom serial port helpers
  */

 #ifndef __OSMO_SERIAL_H__
diff --git a/include/osmocom/core/statistics.h
b/include/osmocom/core/statistics.h
index 04816c1..ade0074 100644
--- a/include/osmocom/core/statistics.h
+++ b/include/osmocom/core/statistics.h
@@ -34,7 +34,7 @@ static inline void osmo_counter_reset(struct
osmo_counter *ctr)
 struct osmo_counter *osmo_counter_alloc(const char *name);

 /*! \brief Free the specified counter
- *  \param[ctr] Counter
+ *  \param[in] ctr Counter
  */
 void osmo_counter_free(struct osmo_counter *ctr);

diff --git a/include/osmocom/gsm/lapd_core.h b/include/osmocom/gsm/lapd_core.h
index 0f4e889..c2fdc62 100644
--- a/include/osmocom/gsm/lapd_core.h
+++ b/include/osmocom/gsm/lapd_core.h
@@ -11,9 +11,9 @@
  *  @{
  */

-/*! \file lapd.h */
-
-/* primitive related sutff */
+/*! \file lapd_core.h
+ * primitive related stuff
+ */

 /*! \brief LAPD related primitives (L2<->L3 SAP)*/
 enum osmo_dl_prim {
@@ -168,4 +168,6 @@ int lapd_set_mode(struct lapd_datalink *dl, enum
lapd_mode mode);
 int lapd_ph_data_ind(struct msgb *msg, struct lapd_msg_ctx *lctx);
 int lapd_recv_dlsap(struct osmo_dlsap_prim *dp, struct lapd_msg_ctx *lctx);

+/*! @} */
+
 #endif /* _OSMOCOM_LAPD_H */
diff --git a/src/bits.c b/src/bits.c
index f3453e5..6be6d7a 100644
--- a/src/bits.c
+++ b/src/bits.c
@@ -180,8 +180,8 @@ uint32_t osmo_revbytebits_8(uint8_t x)
 }

 /*! \brief reverse bit-order of each byte in a buffer
- *  \param buf buffer containing bytes to be bit-reversed
- *  \param[in] length of buffer in bytes
+ *  \param[in] buf buffer containing bytes to be bit-reversed
+ *  \param[in] len length of buffer in bytes
  *
  *  This function reverses the bits in each byte of the buffer
  */
diff --git a/src/bitvec.c b/src/bitvec.c
index 714c11b..8da5a48 100644
--- a/src/bitvec.c
+++ b/src/bitvec.c
@@ -132,7 +132,7 @@ unsigned int bitvec_get_nth_set_bit(const struct
bitvec *bv, unsigned int n)

 /*! \brief set a bit at given position in a bit vector
  *  \param[in] bv bit vector on which to operate
- *  \param[in] bitnum number of bit to be set
+ *  \param[in] bitnr number of bit to be set
  *  \param[in] bit value to which the bit is to be set
  */
 int bitvec_set_bit_pos(struct bitvec *bv, unsigned int bitnr,
diff --git a/src/conv.c b/src/conv.c
index ebc3eda..f13deef 100644
--- a/src/conv.c
+++ b/src/conv.c
@@ -27,7 +27,7 @@
  */

 /*! \file conv.c
- *  \file Osmocom convolutional encoder and decoder
+ * Osmocom convolutional encoder and decoder
  */
 #include "config.h"
 #ifdef HAVE_ALLOCA_H
diff --git a/src/crcXXgen.c.tpl b/src/crcXXgen.c.tpl
index 2a4bf21..7e45c11 100644
--- a/src/crcXXgen.c.tpl
+++ b/src/crcXXgen.c.tpl
@@ -27,7 +27,7 @@
  */

 /*! \file crcXXgen.c
- *  \file Osmocom generic CRC routines (for max XX bits poly)
+ * Osmocom generic CRC routines (for max XX bits poly)
  */

 #include <stdint.h>
diff --git a/src/gsm/auth_core.c b/src/gsm/auth_core.c
index 5cf8dfc..3a0866b 100644
--- a/src/gsm/auth_core.c
+++ b/src/gsm/auth_core.c
@@ -93,7 +93,7 @@ int osmo_auth_supported(enum osmo_auth_algo algo)
 /*! \brief Generate authentication vector
  *  \param[out] vec Generated authentication vector
  *  \param[in] aud Subscriber-specific key material
- *  \param[in] rand Random challenge to be used
+ *  \param[in] _rand Random challenge to be used
  *
  * This function performs the core cryptographic function of the AUC,
  * computing authentication triples/quintuples based on the permanent
@@ -125,7 +125,7 @@ int osmo_auth_gen_vec(struct osmo_auth_vector *vec,
  *  \param[in] aud Subscriber-specific key material
  *  \param[in] rand_auts RAND value sent by the SIM/MS
  *  \param[in] auts AUTS value sent by the SIM/MS
- *  \param[in] rand Random challenge to be used to generate vector
+ *  \param[in] _rand Random challenge to be used to generate vector
  *
  * This function performs a special variant of the  core cryptographic
  * function of the AUC: computing authentication triples/quintuples
diff --git a/src/gsm/lapd_core.c b/src/gsm/lapd_core.c
index 0dc78eb..b33cf6e 100644
--- a/src/gsm/lapd_core.c
+++ b/src/gsm/lapd_core.c
@@ -25,7 +25,7 @@
  *  @{
  */

-/*! \file lapd.c */
+/*! \file lapd_core.c */

 /*!
  * Notes on Buffering: rcv_buffer, tx_queue, tx_hist, send_buffer, send_queue
@@ -2167,3 +2167,4 @@ int lapd_recv_dlsap(struct osmo_dlsap_prim *dp,
struct lapd_msg_ctx *lctx)
 	return rc;
 }

+/*! @} */
diff --git a/src/gsm/tlv_parser.c b/src/gsm/tlv_parser.c
index d18a6bf..8cb2139 100644
--- a/src/gsm/tlv_parser.c
+++ b/src/gsm/tlv_parser.c
@@ -6,7 +6,7 @@
 /*! \addtogroup tlv
  *  @{
  */
-/*! \file tlv.c */
+/*! \file tlv_parser.c */

 struct tlv_definition tvlv_att_def;
 struct tlv_definition vtvlv_gan_att_def;
diff --git a/src/gsmtap_util.c b/src/gsmtap_util.c
index 77ab0c6..82690a9 100644
--- a/src/gsmtap_util.c
+++ b/src/gsmtap_util.c
@@ -49,7 +49,7 @@


 /*! \brief convert RSL channel number to GSMTAP channel type
- *  \param[in] rsl_cantype RSL channel type
+ *  \param[in] rsl_chantype RSL channel type
  *  \param[in] link_id RSL link identifier
  *  \returns GSMTAP channel type
  */
@@ -216,7 +216,7 @@ int gsmtap_source_add_sink_fd(int gsmtap_fd)

 /*! \brief Send a \ref msgb through a GSMTAP source
  *  \param[in] gti GSMTAP instance
- *  \param[in] msgb message buffer
+ *  \param[in] msg message buffer
  */
 int gsmtap_sendmsg(struct gsmtap_inst *gti, struct msgb *msg)
 {
@@ -339,7 +339,7 @@ int gsmtap_source_add_sink(struct gsmtap_inst *gti)
 /*! \brief Open GSMTAP source socket, connect and register osmo_fd
  *  \param[in] host host name or IP address in string format
  *  \param[in] port UDP port number in host byte order
- *  \param[in] osmo_wq_mode Register \ref osmo_wqueue (1) or not (0)
+ *  \param[in] ofd_wq_mode Register \ref osmo_wqueue (1) or not (0)
  *
  * Open GSMTAP source (sending) socket, connect it to host/port,
  * allocate 'struct gsmtap_inst' and optionally osmo_fd/osmo_wqueue
diff --git a/src/msgb.c b/src/msgb.c
index c8564db..359a545 100644
--- a/src/msgb.c
+++ b/src/msgb.c
@@ -74,7 +74,7 @@ void msgb_free(struct msgb *m)

 /*! \brief Enqueue message buffer to tail of a queue
  * \param[in] queue linked list header of queue
- * \param[in] msgb message buffer to be added to the queue
+ * \param[in] msg message buffer to be added to the queue
  *
  * The function will append the specified message buffer \a msg to the
  * queue implemented by \ref llist_head \a queue
@@ -89,7 +89,7 @@ void msgb_enqueue(struct llist_head *queue, struct msgb *msg)
  * \returns message buffer (if any) or NULL if queue empty
  *
  * The function will remove the first message buffer from the queue
- * implemented by 'ref llist_head \a queue.
+ * implemented by \ref llist_head \a queue.
  */
 struct msgb *msgb_dequeue(struct llist_head *queue)
 {
@@ -105,7 +105,7 @@ struct msgb *msgb_dequeue(struct llist_head *queue)
 }

 /*! \brief Re-set all message buffer pointers
- *  \param[in] m message buffer that is to be resetted
+ *  \param[in] msg message buffer that is to be resetted
  *
  * This will re-set the various internal pointers into the underlying
  * message buffer, i.e. remvoe all headroom and treat the msgb as
diff --git a/src/serial.c b/src/serial.c
index a025ae9..66ee756 100644
--- a/src/serial.c
+++ b/src/serial.c
@@ -27,7 +27,7 @@
  */

 /*! \file serial.c
- *  \file Osmocom serial port helpers
+ * Osmocom serial port helpers
  */

 #include <errno.h>
diff --git a/src/socket.c b/src/socket.c
index a5530d0..6ff00f0 100644
--- a/src/socket.c
+++ b/src/socket.c
@@ -129,7 +129,7 @@ int osmo_sock_init(uint16_t family, uint16_t type,
uint8_t proto,
 }

 /*! \brief Initialize a socket and fill \ref osmo_fd
- *  \param[out] osmocom file descriptor (will be filled in)
+ *  \param[out] ofd file descriptor (will be filled in)
  *  \param[in] family Address Family like AF_INET, AF_INET6, AF_UNSPEC
  *  \param[in] type Socket type like SOCK_DGRAM, SOCK_STREAM
  *  \param[in] proto Protocol like IPPROTO_TCP, IPPROTO_UDP
diff --git a/src/timer.c b/src/timer.c
index 98cbf6e..5988aef 100644
--- a/src/timer.c
+++ b/src/timer.c
@@ -128,7 +128,7 @@ int osmo_timer_pending(struct osmo_timer_list *timer)

 /*! \brief compute the remaining time of a timer
  *  \param[in] timer the to-be-checked timer
- *  \param[in] the current time (NULL if not known)
+ *  \param[in] now the current time (NULL if not known)
  *  \param[out] remaining remaining time until timer fires
  *  \return 0 if timer has not expired yet, -1 if it has
  *
-- 
1.7.9.5

    

Katerina Barone-Adesi

Holger Hans Peter Freyther

tags

participants (2)