openocd: fix incorrect doxygen comments

Use '@param' in front of function's parameters and '@a' when the
parameter is recalled in the description.

This fixes doxygen complains:
	warning: Found unknown command '@buff16'

While there, fix a minor typo s/occured/occurred/ in a comment and
the typo s/@apram/@param/ in a doxygen comment.

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

src/jtag/drivers/jtag_dpi.c

@@ -79,8 +79,8 @@ static int read_sock(char *buf, size_t len)
 
 /**
  * jtag_dpi_reset - ask to reset the JTAG device
- * @trst: 1 if TRST is to be asserted
- * @srst: 1 if SRST is to be asserted
+ * @param trst 1 if TRST is to be asserted
+ * @param srst 1 if SRST is to be asserted
  */
 static int jtag_dpi_reset(int trst, int srst)
 {
@@ -109,11 +109,11 @@ static int jtag_dpi_reset(int trst, int srst)
 
 /**
  * jtag_dpi_scan - launches a DR-scan or IR-scan
- * @cmd: the command to launch
+ * @param cmd the command to launch
  *
  * Launch a JTAG IR-scan or DR-scan
  *
- * Returns ERROR_OK if OK, ERROR_xxx if a read/write error occured.
+ * Returns ERROR_OK if OK, ERROR_xxx if a read/write error occurred.
  */
 static int jtag_dpi_scan(struct scan_command *cmd)
 {

src/jtag/drivers/jtag_vpi.c

@@ -208,8 +208,8 @@ static int jtag_vpi_receive_cmd(struct vpi_cmd *vpi)
 
 /**
  * jtag_vpi_reset - ask to reset the JTAG device
- * @trst: 1 if TRST is to be asserted
- * @srst: 1 if SRST is to be asserted
+ * @param trst 1 if TRST is to be asserted
+ * @param srst 1 if SRST is to be asserted
  */
 static int jtag_vpi_reset(int trst, int srst)
 {
@@ -223,8 +223,8 @@ static int jtag_vpi_reset(int trst, int srst)
 
 /**
  * jtag_vpi_tms_seq - ask a TMS sequence transition to JTAG
- * @bits: TMS bits to be written (bit0, bit1 .. bitN)
- * @nb_bits: number of TMS bits (between 1 and 8)
+ * @param bits TMS bits to be written (bit0, bit1 .. bitN)
+ * @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=<???>
@@ -250,7 +250,7 @@ static int jtag_vpi_tms_seq(const uint8_t *bits, int nb_bits)
 
 /**
  * jtag_vpi_path_move - ask a TMS sequence transition to JTAG
- * @cmd: path transition
+ * @param cmd path transition
  *
  * Write a series of TMS transitions, where each transition consists in :
  *  - writing out TCK=0, TMS=<new_state>, TDI=<???>
@@ -276,7 +276,7 @@ static int jtag_vpi_path_move(struct pathmove_command *cmd)
 
 /**
  * jtag_vpi_tms - ask a tms command
- * @cmd: tms command
+ * @param cmd tms command
  */
 static int jtag_vpi_tms(struct tms_command *cmd)
 {
@@ -342,8 +342,8 @@ static int jtag_vpi_queue_tdi_xfer(uint8_t *bits, int nb_bits, int tap_shift)
 
 /**
  * jtag_vpi_queue_tdi - short description
- * @bits: bits to be queued on TDI (or NULL if 0 are to be queued)
- * @nb_bits: number of bits
+ * @param bits bits to be queued on TDI (or NULL if 0 are to be queued)
+ * @param nb_bits number of bits
  */
 static int jtag_vpi_queue_tdi(uint8_t *bits, int nb_bits, int tap_shift)
 {
@@ -372,7 +372,7 @@ static int jtag_vpi_queue_tdi(uint8_t *bits, int nb_bits, int tap_shift)
 
 /**
  * jtag_vpi_clock_tms - clock a TMS transition
- * @tms: the TMS to be sent
+ * @param tms the TMS to be sent
  *
  * Triggers a TMS transition (ie. one JTAG TAP state move).
  */
@@ -386,7 +386,7 @@ static int jtag_vpi_clock_tms(int tms)
 
 /**
  * jtag_vpi_scan - launches a DR-scan or IR-scan
- * @cmd: the command to launch
+ * @param cmd the command to launch
  *
  * Launch a JTAG IR-scan or DR-scan
  *

src/jtag/drivers/usb_blaster/usb_blaster.c

@@ -253,7 +253,7 @@ static void ublast_flush_buffer(void)
 
 /**
  * ublast_queue_byte - queue one 'bitbang mode' byte for USB Blaster
- * @abyte: the byte to queue
+ * @param abyte the byte to queue
  *
  * Queues one byte in 'bitbang mode' to the USB Blaster. The byte is not
  * actually sent, but stored in a buffer. The write is performed once
@@ -271,7 +271,7 @@ static void ublast_queue_byte(uint8_t abyte)
 
 /**
  * ublast_compute_pin - compute if gpio should be asserted
- * @steer: control (ie. TRST driven, SRST driven, of fixed)
+ * @param steer control (ie. TRST driven, SRST driven, of fixed)
  *
  * Returns pin value (1 means driven high, 0 mean driven low)
  */
@@ -293,7 +293,7 @@ static bool ublast_compute_pin(enum gpio_steer steer)
 
 /**
  * ublast_build_out - build bitbang mode output byte
- * @type: says if reading back TDO is required
+ * @param type says if reading back TDO is required
  *
  * Returns the compute bitbang mode byte
  */
@@ -313,8 +313,8 @@ static uint8_t ublast_build_out(enum scan_type type)
 
 /**
  * ublast_reset - reset the JTAG device is possible
- * @trst: 1 if TRST is to be asserted
- * @srst: 1 if SRST is to be asserted
+ * @param trst 1 if TRST is to be asserted
+ * @param srst 1 if SRST is to be asserted
  */
 static void ublast_reset(int trst, int srst)
 {
@@ -329,7 +329,7 @@ static void ublast_reset(int trst, int srst)
 
 /**
  * ublast_clock_tms - clock a TMS transition
- * @tms: the TMS to be sent
+ * @param tms the TMS to be sent
  *
  * Triggers a TMS transition (ie. one JTAG TAP state move).
  */
@@ -360,8 +360,8 @@ static void ublast_idle_clock(void)
 
 /**
  * ublast_clock_tdi - Output a TDI with bitbang mode
- * @tdi: the TDI bit to be shifted out
- * @type: scan type (ie. does a readback of TDO is required)
+ * @param tdi the TDI bit to be shifted out
+ * @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>
@@ -387,8 +387,8 @@ static void ublast_clock_tdi(int tdi, enum scan_type type)
 
 /**
  * ublast_clock_tdi_flip_tms - Output a TDI with bitbang mode, change JTAG state
- * @tdi: the TDI bit to be shifted out
- * @type: scan type (ie. does a readback of TDO is required)
+ * @param tdi the TDI bit to be shifted out
+ * @param type scan type (ie. does a readback of TDO is required)
  *
  * This function is the same as ublast_clock_tdi(), but it changes also the TMS
  * while output the TDI. This should be the last TDI output of a TDI
@@ -416,8 +416,8 @@ static void ublast_clock_tdi_flip_tms(int tdi, enum scan_type type)
 
 /**
  * ublast_queue_bytes - queue bytes for the USB Blaster
- * @bytes: byte array
- * @nb_bytes: number of bytes
+ * @param bytes byte array
+ * @param nb_bytes number of bytes
  *
  * Queues bytes to be sent to the USB Blaster. The bytes are not
  * actually sent, but stored in a buffer. The write is performed once
@@ -443,9 +443,9 @@ static void ublast_queue_bytes(uint8_t *bytes, int nb_bytes)
 
 /**
  * ublast_tms_seq - write a TMS sequence transition to JTAG
- * @bits: TMS bits to be written (bit0, bit1 .. bitN)
- * @nb_bits: number of TMS bits (between 1 and 8)
- * @skip: number of TMS bits to skip at the beginning of the series
+ * @param bits TMS bits to be written (bit0, bit1 .. bitN)
+ * @param nb_bits number of TMS bits (between 1 and 8)
+ * @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=<???>
@@ -465,7 +465,7 @@ static void ublast_tms_seq(const uint8_t *bits, int nb_bits, int skip)
 
 /**
  * ublast_tms - write a tms command
- * @cmd: tms command
+ * @param cmd tms command
  */
 static void ublast_tms(struct tms_command *cmd)
 {
@@ -475,7 +475,7 @@ static void ublast_tms(struct tms_command *cmd)
 
 /**
  * ublast_path_move - write a TMS sequence transition to JTAG
- * @cmd: path transition
+ * @param cmd path transition
  *
  * Write a series of TMS transitions, where each transition consists in :
  *  - writing out TCK=0, TMS=<new_state>, TDI=<???>
@@ -501,8 +501,8 @@ static void ublast_path_move(struct pathmove_command *cmd)
 
 /**
  * ublast_state_move - move JTAG state to the target state
- * @state: the target state
- * @skip: number of bits to skip at the beginning of the path
+ * @param state the target state
+ * @param skip number of bits to skip at the beginning of the path
  *
  * Input the correct TMS sequence to the JTAG TAP so that we end up in the
  * target state. This assumes the current state (tap_get_state()) is correct.
@@ -524,8 +524,8 @@ static void ublast_state_move(tap_state_t state, int skip)
 
 /**
  * ublast_read_byteshifted_tdos - read TDO of byteshift writes
- * @buf: the buffer to store the bits
- * @nb_bits: the number of bits
+ * @param buf the buffer to store the bits
+ * @param nb_bits the number of bits
  *
  * 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.
@@ -552,8 +552,8 @@ static int ublast_read_byteshifted_tdos(uint8_t *buf, int nb_bytes)
 
 /**
  * ublast_read_bitbang_tdos - read TDO of bitbang writes
- * @buf: the buffer to store the bits
- * @nb_bits: the number of bits
+ * @param buf the buffer to store the bits
+ * @param nb_bits the number of bits
  *
  * Reads back from USB Blaster TDO bits, triggered by a 'bitbang write', ie. one
  * bit per received byte from USB interface, and store them in buffer, where :
@@ -592,9 +592,9 @@ static int ublast_read_bitbang_tdos(uint8_t *buf, int nb_bits)
 
 /**
  * ublast_queue_tdi - short description
- * @bits: bits to be queued on TDI (or NULL if 0 are to be queued)
- * @nb_bits: number of bits
- * @scan: scan type (ie. if TDO read back is required or not)
+ * @param bits bits to be queued on TDI (or NULL if 0 are to be queued)
+ * @param nb_bits number of bits
+ * @param scan scan type (ie. if TDO read back is required or not)
  *
  * Outputs a series of TDI bits on TDI.
  * As a side effect, the last TDI bit is sent along a TMS=1, and triggers a JTAG
@@ -703,7 +703,7 @@ static void ublast_stableclocks(int cycles)
 
 /**
  * ublast_scan - launches a DR-scan or IR-scan
- * @cmd: the command to launch
+ * @param cmd the command to launch
  *
  * Launch a JTAG IR-scan or DR-scan
  *