openocd: fix doxygen parameters of functions

Add to doxygen comment the missing parameters.
Remove from doxygen comment any non-existing parameter.
Fix the parameter names in doxygen comment to match the one in the
function prototype.
Where the parameter name in the doxygen description seems better
than the one in the code, change the code.
Escape the character '<' to prevent doxygen to interpret it as an
xml tag.

Change-Id: I22da723339ac7d7a7a64ac4c1cc4336e2416c2cc
Signed-off-by: Antonio Borneo <borneo.antonio@gmail.com>
Reviewed-on: http://openocd.zylin.com/6002
Tested-by: jenkins

5 files changed, 18 insertions, 12 deletions

diff --git a/src/jtag/drivers/OpenULINK/src/jtag.c b/src/jtag/drivers/OpenULINK/src/jtag.c
index ecf98a0..c76f034 100644
--- a/src/jtag/drivers/OpenULINK/src/jtag.c
+++ b/src/jtag/drivers/OpenULINK/src/jtag.c
@@ -48,6 +48,7 @@ uint8_t delay_tms;
  * Maximum achievable TCK frequency is 182 kHz for ULINK clocked at 24 MHz.
  *
  * @param out_offset offset in OUT2BUF where payload data starts
+ * @param in_offset
  */
 void jtag_scan_in(uint8_t out_offset, uint8_t in_offset)
 {
@@ -125,6 +126,7 @@ void jtag_scan_in(uint8_t out_offset, uint8_t in_offset)
  * Maximum achievable TCK frequency is 113 kHz for ULINK clocked at 24 MHz.
  *
  * @param out_offset offset in OUT2BUF where payload data starts
+ * @param in_offset
  */
 void jtag_slow_scan_in(uint8_t out_offset, uint8_t in_offset)
 {
@@ -373,6 +375,7 @@ void jtag_slow_scan_out(uint8_t out_offset)
  * Maximum achievable TCK frequency is 100 kHz for ULINK clocked at 24 MHz.
  *
  * @param out_offset offset in OUT2BUF where payload data starts
+ * @param in_offset
  */
 void jtag_scan_io(uint8_t out_offset, uint8_t in_offset)
 {
@@ -465,6 +468,7 @@ void jtag_scan_io(uint8_t out_offset, uint8_t in_offset)
  * Maximum achievable TCK frequency is 78 kHz for ULINK clocked at 24 MHz.
  *
  * @param out_offset offset in OUT2BUF where payload data starts
+ * @param in_offset
  */
 void jtag_slow_scan_io(uint8_t out_offset, uint8_t in_offset)
 {
diff --git a/src/jtag/drivers/ftdi.c b/src/jtag/drivers/ftdi.c
index 4fa83ae..9d1c85c 100644
--- a/src/jtag/drivers/ftdi.c
+++ b/src/jtag/drivers/ftdi.c
@@ -1062,7 +1062,6 @@ static void ftdi_swd_swdio_en(bool enable)
 
 /**
  * Flush the MPSSE queue and process the SWD transaction queue
- * @param dap
  * @return
  */
 static int ftdi_swd_run_queue(void)
diff --git a/src/jtag/drivers/jtag_vpi.c b/src/jtag/drivers/jtag_vpi.c
index a6609d2..c5ffe83 100644
--- a/src/jtag/drivers/jtag_vpi.c
+++ b/src/jtag/drivers/jtag_vpi.c
@@ -227,8 +227,8 @@ static int jtag_vpi_reset(int trst, int srst)
  * @param nb_bits number of TMS bits (between 1 and 8)
  *
  * Write a series of TMS transitions, where each transition consists in :
- *  - writing out TCK=0, TMS=<new_state>, TDI=<???>
- *  - writing out TCK=1, TMS=<new_state>, TDI=<???> which triggers the transition
+ *  - writing out TCK=0, TMS=\<new_state>, TDI=\<???>
+ *  - writing out TCK=1, TMS=\<new_state>, TDI=\<???> which triggers the transition
  * The function ensures that at the end of the sequence, the clock (TCK) is put
  * low.
  */
@@ -253,8 +253,8 @@ static int jtag_vpi_tms_seq(const uint8_t *bits, int nb_bits)
  * @param cmd path transition
  *
  * Write a series of TMS transitions, where each transition consists in :
- *  - writing out TCK=0, TMS=<new_state>, TDI=<???>
- *  - writing out TCK=1, TMS=<new_state>, TDI=<???> which triggers the transition
+ *  - writing out TCK=0, TMS=\<new_state>, TDI=\<???>
+ *  - writing out TCK=1, TMS=\<new_state>, TDI=\<???> which triggers the transition
  * The function ensures that at the end of the sequence, the clock (TCK) is put
  * low.
  */
@@ -344,6 +344,7 @@ static int jtag_vpi_queue_tdi_xfer(uint8_t *bits, int nb_bits, int tap_shift)
  * jtag_vpi_queue_tdi - short description
  * @param bits bits to be queued on TDI (or NULL if 0 are to be queued)
  * @param nb_bits number of bits
+ * @param tap_shift
  */
 static int jtag_vpi_queue_tdi(uint8_t *bits, int nb_bits, int tap_shift)
 {
diff --git a/src/jtag/drivers/ulink.c b/src/jtag/drivers/ulink.c
index f473ce3..ccc023f 100644
--- a/src/jtag/drivers/ulink.c
+++ b/src/jtag/drivers/ulink.c
@@ -696,6 +696,7 @@ static int ulink_append_queue(struct ulink *device, struct ulink_cmd *ulink_cmd)
  * Sends all queued OpenULINK commands to the ULINK for execution.
  *
  * @param device pointer to struct ulink identifying ULINK driver instance.
+ * @param timeout
  * @return on success: ERROR_OK
  * @return on failure: ERROR_FAIL
  */
@@ -1682,6 +1683,7 @@ static int ulink_queue_runtest(struct ulink *device, struct jtag_command *cmd)
 /**
  * Execute a JTAG_RESET command
  *
+ * @param device
  * @param cmd pointer to the command that shall be executed.
  * @return on success: ERROR_OK
  * @return on failure: ERROR_FAIL
diff --git a/src/jtag/drivers/usb_blaster/usb_blaster.c b/src/jtag/drivers/usb_blaster/usb_blaster.c
index 5559bce..5002a5f 100644
--- a/src/jtag/drivers/usb_blaster/usb_blaster.c
+++ b/src/jtag/drivers/usb_blaster/usb_blaster.c
@@ -364,8 +364,8 @@ static void ublast_idle_clock(void)
  * @param type scan type (ie. does a readback of TDO is required)
  *
  * Output a TDI bit and assert clock to push it into the JTAG device :
- *  - writing out TCK=0, TMS=<old_state>=0, TDI=<tdi>
- * - writing out TCK=1, TMS=<new_state>, TDI=<tdi> which triggers the JTAG
+ *  - writing out TCK=0, TMS=\<old_state>=0, TDI=\<tdi>
+ *  - writing out TCK=1, TMS=\<new_state>, TDI=\<tdi> which triggers the JTAG
  *    device acquiring the data.
  *
  * If a TDO is to be read back, the required read is requested (bitbang mode),
@@ -448,8 +448,8 @@ static void ublast_queue_bytes(uint8_t *bytes, int nb_bytes)
  * @param skip number of TMS bits to skip at the beginning of the series
  *
  * Write a series of TMS transitions, where each transition consists in :
- *  - writing out TCK=0, TMS=<new_state>, TDI=<???>
- *  - writing out TCK=1, TMS=<new_state>, TDI=<???> which triggers the transition
+ *  - writing out TCK=0, TMS=\<new_state>, TDI=\<???>
+ *  - writing out TCK=1, TMS=\<new_state>, TDI=\<???> which triggers the transition
  * The function ensures that at the end of the sequence, the clock (TCK) is put
  * low.
  */
@@ -478,8 +478,8 @@ static void ublast_tms(struct tms_command *cmd)
  * @param cmd path transition
  *
  * Write a series of TMS transitions, where each transition consists in :
- *  - writing out TCK=0, TMS=<new_state>, TDI=<???>
- *  - writing out TCK=1, TMS=<new_state>, TDI=<???> which triggers the transition
+ *  - writing out TCK=0, TMS=\<new_state>, TDI=\<???>
+ *  - writing out TCK=1, TMS=\<new_state>, TDI=\<???> which triggers the transition
  * The function ensures that at the end of the sequence, the clock (TCK) is put
  * low.
  */
@@ -525,7 +525,7 @@ static void ublast_state_move(tap_state_t state, int skip)
 /**
  * ublast_read_byteshifted_tdos - read TDO of byteshift writes
  * @param buf the buffer to store the bits
- * @param nb_bits the number of bits
+ * @param nb_bytes the number of bytes
  *
  * Reads back from USB Blaster TDO bits, triggered by a 'byteshift write', ie. eight
  * bits per received byte from USB interface, and store them in buffer.