From ee0607b8a7ff7eb755d32719c4bd7b6920447c1f Mon Sep 17 00:00:00 2001 From: jonas Date: Tue, 6 Oct 2020 08:57:40 +0200 Subject: "Dogxygen style" function commenting. --- o3000.c | 42 +++++++++++++++++++++--------------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/o3000.c b/o3000.c index dd99f97..31d1adc 100644 --- a/o3000.c +++ b/o3000.c @@ -60,22 +60,22 @@ Two groups of functions represent the interface: The basic approach using the camera driver is:
  1. Implementing all required callback functions, see @ref cb_fun.
    2. -
  2. Initialising the camera driver, see o3000_init().
    3. -
  3. Connecting to the camera driver, see o3000_connect().
    4. +
  4. Initialising the camera driver, see @ref o3000_init.
    5. +
  5. Connecting to the camera driver, see @ref o3000_connect.
-Once the user application is connected to the driver by calling o3000_connect(), it will block until: +Once the user application is connected to the driver by calling @ref o3000_connect, it will block until: -XML messages are transfered to the camera by calling o3000_send_xml(). If the camera sends a XML message to the host, the +XML messages are transfered to the camera by calling @ref o3000_send_xml. If the camera sends a XML message to the host, the driver triggers the @ref xml_cb. The same concept is used, when the camera sends video data to the host. After receving a complete frame, the driver calls the @ref video_cb. -@note The video driver triggers any callback from the thread context, where o3000_connect() is called from. This means that the o3000_send_xml() function should -never be called from the Video, XML or Logging callback. Otherwise the driver will lock. It's important, that any XML message sent with o3000_send_xml() to the camera +@note The video driver triggers any callback from the thread context, where @ref o3000_connect is called from. This means that the @ref o3000_send_xml function should +never be called from the Video, XML or Logging callback. Otherwise the driver will lock. It's important, that any XML message sent with @ref o3000_send_xml to the camera is called from a different thread context. @@ -107,7 +107,7 @@ containing the log message. This handler is optional. A simplified example with C is shown below, focussing on the order in which the various camera driver functions should be called. It's up to the user to implement -multithreading in order to avoid a deadlock due to the blocking nature of o3000_connect()! +multithreading in order to avoid a deadlock due to the blocking nature of @ref o3000_connect! @code @@ -828,7 +828,7 @@ static int send_xml(struct o3000_session_t *session, const char *msg, int msg_le /** * Send XML packet from host to device. * - * @note Never call this function from the thread context o3000_connect() is called from! + * @note Never call this function from the thread context @ref o3000_connect is called from! * * @param id session ID * @param msg message content @@ -870,9 +870,9 @@ int __stdcall o3000_send_xml(int id, const char *msg, int msg_len) { /** * Disconnect a currently claimed USB connection. - * Use this function if the driver is connected to an USB device. The o3000_connect() function-call is blocking now. - * After disconnecting, the function o3000_connect() returns. The session is not cleaned-up due to the driver is ready the reconnect - * to the same USB device by calling o3000_connect() again. + * Use this function if the driver is connected to an USB device. The @ref o3000_connect function-call is blocking now. + * After disconnecting, the function @ref o3000_connect returns. The session is not cleaned-up due to the driver is ready the reconnect + * to the same USB device by calling @ref o3000_connect again. * * @param id session ID * @return 0 on success, or error code defined at @ref o3000.h. @@ -913,16 +913,16 @@ int __stdcall o3000_disconnect(int id) { /** * Estabslish a connection to an existing device. * If several devices are available on the same system, the device number is used. The number of devices are requested - * by o3000_get_num_device(). + * by @ref o3000_get_num_device. * * NOTE - * This function will block until the USB device is disconnected manually or the driver is stopped by calling o3000_exit(). + * This function will block until the USB device is disconnected manually or the driver is stopped by calling @ref o3000_exit. * * @param id session ID * @param device_nr device number to connect (use 0 to connect to first available device) * @param config_msg configuration message to be sent to device after successful connection, or NULL if not used * @param config_msg_len configuration message length - * @return 0 is returned only after calling dmm_exit() or dmm_disconnect(). Otherwise the error code defined at @ref o3000.h. + * @return 0 is returned only after calling @ref dmm_exit or @ref dmm_disconnect. Otherwise the error code defined at @ref o3000.h. */ int __stdcall o3000_connect(int id, int device_nr, char *config_msg, int config_msg_len) { @@ -1052,12 +1052,12 @@ int __stdcall o3000_connect(int id, int device_nr, char *config_msg, int config_ /* * There are following reasons to get here: * - * 1. o3000_disconnect() was called - * 2. o3000_exit() was called + * 1. o3000_disconnect was called + * 2. o3000_exit was called * 3. the device isn't available anymore because it was unplugged, it does an USB hardware reset * - * The current session is cleaned-up only if o3000_exit() has been called. Otherwise the session will further exist and a reconnection with o3000_connect() will be allowed. - * Actually, it doesn't make any sense to connect to an unavailable device. But to keep it simple, a session is cleaned-up only with o3000_exit() without any exception. + * The current session is cleaned-up only if o3000_exit has been called. Otherwise the session will further exist and a reconnection with o3000_connect will be allowed. + * Actually, it doesn't make any sense to connect to an unavailable device. But to keep it simple, a session is cleaned-up only with o3000_exit without any exception. */ if(session->release_session == FALSE && session->disconnect_dev == FALSE) { // device was unplugged (see reason 3 few lines above) @@ -1076,7 +1076,7 @@ int __stdcall o3000_connect(int id, int device_nr, char *config_msg, int config_ session->dev = NULL; } - // release session due to o3000_exit() call + // release session due to o3000_exit call if(session->release_session == TRUE) { o3000_log(session, O3000_LOG_DEBUG, "%s: cleanup session\n", __func__); session->release_session = FALSE; @@ -1098,7 +1098,7 @@ _connect_abort: /** * The device discovery returns the number of USB devices in question. * In fact, the number of devices with the session PID/VID are counted. After knowing the number of devices, any connection can be - * established with o3000_connect(). + * established with @ref o3000_connect. * * @param id valid session ID * @return number of USB device or a negative return code -- cgit v1.2.1