From: Matthias Heidbrink Date: Fri, 22 Nov 2013 19:40:52 +0000 (+0100) Subject: Improved doxygen docs. X-Git-Tag: libsigrok-0.3.0~447 X-Git-Url: https://sigrok.org/gitweb/?p=libsigrok.git;a=commitdiff_plain;h=04cb915716ecdc1ee26440b4c09bc2f2de183631 Improved doxygen docs. --- diff --git a/backend.c b/backend.c index 0d1b4726..41c74c7c 100644 --- a/backend.c +++ b/backend.c @@ -119,7 +119,8 @@ extern struct sr_session *session; /** * Sanity-check all libsigrok drivers. * - * @return SR_OK if all drivers are OK, SR_ERR if one or more have issues. + * @retval SR_OK All drivers are OK + * @retval SR_ERR One or more drivers have issues. */ static int sanity_check_all_drivers(void) { @@ -209,7 +210,8 @@ static int sanity_check_all_drivers(void) /** * Sanity-check all libsigrok input modules. * - * @return SR_OK if all modules are OK, SR_ERR if one or more have issues. + * @retval SR_OK All modules are OK + * @retval SR_ERR One or more modules have issues. */ static int sanity_check_all_input_modules(void) { @@ -258,7 +260,8 @@ static int sanity_check_all_input_modules(void) /** * Sanity-check all libsigrok output modules. * - * @return SR_OK if all modules are OK, SR_ERR if one or more have issues. + * @retval SR_OK All modules are OK + * @retval SR_ERR One or more modules have issues. */ static int sanity_check_all_output_modules(void) { @@ -382,7 +385,8 @@ done: * * @param ctx Pointer to a libsigrok context struct. Must not be NULL. * - * @return SR_OK upon success, a (negative) error code otherwise. + * @retval SR_OK Success + * @retval other Error code SR_ERR, ... * * @since 0.2.0 */ diff --git a/device.c b/device.c index 987f4562..4484c8dc 100644 --- a/device.c +++ b/device.c @@ -46,7 +46,15 @@ * @{ */ -/** @private */ +/** @private + * Allocate and initialize new struct sr_probe + * @param[in] index \copydoc sr_probe::index + * @param[in] type \copydoc sr_probe::type + * @param[in] enabled \copydoc sr_probe::enabled + * @param[in] name \copydoc sr_probe::name + * + * @return NULL (failure) or new struct sr_probe*. + */ SR_PRIV struct sr_probe *sr_probe_new(int index, int type, gboolean enabled, const char *name) { @@ -73,9 +81,9 @@ SR_PRIV struct sr_probe *sr_probe_new(int index, int type, * removed, and the new name will be saved instead. * * @param sdi The device instance the probe is connected to. - * @param probenum The number of the probe whose name to set. + * @param[in] probenum The number of the probe whose name to set. * Note that the probe numbers start at 0. - * @param name The new name that the specified probe should get. A copy + * @param[in] name The new name that the specified probe should get. A copy * of the string is made. * * @return SR_OK on success, or SR_ERR_ARG on invalid arguments. @@ -148,9 +156,9 @@ SR_API int sr_dev_probe_enable(const struct sr_dev_inst *sdi, int probenum, * If the specified probe of this device already has a trigger, it will * be silently replaced. * - * @param sdi Must not be NULL. - * @param probenum The probe number, starting from 0. - * @param trigger Trigger string, in the format used by sigrok-cli + * @param[in,out] sdi Pointer to the device instance; must not be NULL. + * @param[in] probenum Number of probe, starting at 0. + * @param[in] trigger Trigger string, in the format used by sigrok-cli * * @return SR_OK on success, or SR_ERR_ARG on invalid arguments. * @@ -189,12 +197,12 @@ SR_API int sr_dev_trigger_set(const struct sr_dev_inst *sdi, int probenum, * If the device's 'driver' field is NULL (virtual device), this * function will always return FALSE (virtual devices don't have * a hardware capabilities list). - * @param key The option that should be checked for support on the + * @param[in] key The option that should be checked for is supported by the * specified device. * - * @return TRUE if the device has the specified option, FALSE otherwise. - * FALSE is also returned on invalid input parameters or other - * error conditions. + * @retval TRUE Device has the specified option + * @retval FALSE Device does not have the specified option, invalid input + * parameters or other error conditions. * * @since 0.2.0 */ @@ -225,7 +233,18 @@ SR_API gboolean sr_dev_has_option(const struct sr_dev_inst *sdi, int key) return ret; } -/** @private */ +/** @private + * Allocate and init new device instance struct. + * \param[in] index \copydoc sr_dev_inst::index + * \param[in] status \copydoc sr_dev_inst::status + * \param[in] vendor \copydoc sr_dev_inst::vendor + * \param[in] model \copydoc sr_dev_inst::model + * \param[in] version \copydoc sr_dev_inst::version + * + * \retval NULL Error + * \retval struct sr_dev_inst *. Dynamically allocated, free using + * sr_dev_inst_free(). + */ SR_PRIV struct sr_dev_inst *sr_dev_inst_new(int index, int status, const char *vendor, const char *model, const char *version) { @@ -251,7 +270,10 @@ SR_PRIV struct sr_dev_inst *sr_dev_inst_new(int index, int status, return sdi; } -/** @private */ +/** @private + * Free device instance struct created by sr_dev_inst(). + * \param sdi struct* to free. + */ SR_PRIV void sr_dev_inst_free(struct sr_dev_inst *sdi) { struct sr_probe *probe; @@ -276,7 +298,15 @@ SR_PRIV void sr_dev_inst_free(struct sr_dev_inst *sdi) #ifdef HAVE_LIBUSB_1_0 -/** @private */ +/** @private + * Allocate and init struct for USB device instance. + * \param[in] bus \copydoc sr_usb_dev_inst::bus + * \param[in] address \copydoc sr_usb_dev_inst::address + * \param[in] hdl \copydoc sr_usb_dev_inst::devhdl + * + * \retval NULL Error + * \retval other struct sr_usb_dev_inst * for USB device instance. + */ SR_PRIV struct sr_usb_dev_inst *sr_usb_dev_inst_new(uint8_t bus, uint8_t address, struct libusb_device_handle *hdl) { @@ -294,7 +324,10 @@ SR_PRIV struct sr_usb_dev_inst *sr_usb_dev_inst_new(uint8_t bus, return udi; } -/** @private */ +/** @private + * Free struct * allocated by sr_usb_dev_inst(). + * \param usb struct* to free. Must not be NULL. + */ SR_PRIV void sr_usb_dev_inst_free(struct sr_usb_dev_inst *usb) { g_free(usb); @@ -310,12 +343,12 @@ SR_PRIV void sr_usb_dev_inst_free(struct sr_usb_dev_inst *usb) * Both parameters are copied to newly allocated strings, and freed * automatically by sr_serial_dev_inst_free(). * - * @param pathname OS-specific serial port specification. Examples: + * @param[in] port OS-specific serial port specification. Examples: * "/dev/ttyUSB0", "/dev/ttyACM1", "/dev/tty.Modem-0", "COM1". - * @param serialcomm A serial communication parameters string, in the form - * of /, for example - * "9600/8n1" or "600/7o2". This is an optional parameter; - * it may be filled in later. + * @param[in] serialcomm A serial communication parameters string, in the form + * of \/\\\, for example + * "9600/8n1" or "600/7o2". This is an optional parameter; + * it may be filled in later. * * @return A pointer to a newly initialized struct sr_serial_dev_inst, * or NULL on error. @@ -342,7 +375,10 @@ SR_PRIV struct sr_serial_dev_inst *sr_serial_dev_inst_new(const char *port, return serial; } -/** @private */ +/** @private + * Free struct sr_serial_dev_inst * allocated by sr_serial_dev_inst(). + * \param serial struct sr_serial_dev_inst * to free. Must not be NULL. + */ SR_PRIV void sr_serial_dev_inst_free(struct sr_serial_dev_inst *serial) { g_free(serial->port); diff --git a/hardware/common/serial.c b/hardware/common/serial.c index 554dbb9b..9727ce8a 100644 --- a/hardware/common/serial.c +++ b/hardware/common/serial.c @@ -268,14 +268,17 @@ SR_PRIV int serial_read(struct sr_serial_dev_inst *serial, void *buf, * Set serial parameters for the specified serial port. * * @param serial Previously initialized serial port structure. - * @param baudrate The baudrate to set. - * @param bits The number of data bits to use. - * @param parity The parity setting to use (0 = none, 1 = even, 2 = odd). - * @param stopbits The number of stop bits to use (1 or 2). - * @param flowcontrol The flow control settings to use (0 = none, 1 = RTS/CTS, - * 2 = XON/XOFF). + * @param[in] baudrate The baudrate to set. + * @param[in] bits The number of data bits to use (5, 6, 7 or 8). + * @param[in] parity The parity setting to use (0 = none, 1 = even, 2 = odd). + * @param[in] stopbits The number of stop bits to use (1 or 2). + * @param[in] flowcontrol The flow control settings to use (0 = none, + * 1 = RTS/CTS, 2 = XON/XOFF). + * @param[in] rts Status of RTS line (0 or 1; required by some interfaces). + * @param[in] dtr Status of DTR line (0 or 1; required by some interfaces). * - * @return SR_OK upon success, SR_ERR upon failure. + * @retval SR_OK Success + * @retval SR_ERR Failure. */ SR_PRIV int serial_set_params(struct sr_serial_dev_inst *serial, int baudrate, int bits, int parity, int stopbits, @@ -341,11 +344,13 @@ SR_PRIV int serial_set_params(struct sr_serial_dev_inst *serial, int baudrate, * Set serial parameters for the specified serial port. * * @param serial Previously initialized serial port structure. - * @param paramstr A serial communication parameters string, in the form - * of /, for example "9600/8n1" or - * "600/7o2" or "460800/8n1/flow=2" where flow is 0 for none, 1 for rts/cts and 2 for xon/xoff. + * @param[in] paramstr A serial communication parameters string, in the form + * of \/\\\\, for example + * "9600/8n1" or "600/7o2" or "460800/8n1/flow=2" where flow is 0 for none, + * 1 for rts/cts and 2 for xon/xoff. * - * @return SR_OK upon success, SR_ERR upon failure. + * @retval SR_OK Success. + * @retval SR_ERR Failure. */ #define SERIAL_COMM_SPEC "^(\\d+)/([5678])([neo])([12])(.*)$" SR_PRIV int serial_set_paramstr(struct sr_serial_dev_inst *serial, @@ -448,11 +453,12 @@ SR_PRIV int serial_set_paramstr(struct sr_serial_dev_inst *serial, * @param serial Previously initialized serial port structure. * @param buf Buffer where to store the bytes that are read. * @param buflen Size of the buffer. - * @param timeout_ms How long to wait for a line to come in. + * @param[in] timeout_ms How long to wait for a line to come in. * * Reading stops when CR of LR is found, which is stripped from the buffer. * - * @return SR_OK on success, SR_ERR on failure. + * @retval SR_OK Success. + * @retval SR_ERR Failure. */ SR_PRIV int serial_readline(struct sr_serial_dev_inst *serial, char **buf, int *buflen, gint64 timeout_ms) @@ -507,17 +513,17 @@ SR_PRIV int serial_readline(struct sr_serial_dev_inst *serial, char **buf, * * @param serial Previously initialized serial port structure. * @param buf Buffer containing the bytes to write. - * @param count Size of the buffer. - * @param packet_size Size, in bytes, of a valid packet. + * @param buflen Size of the buffer. + * @param[in] packet_size Size, in bytes, of a valid packet. * @param is_valid Callback that assesses whether the packet is valid or not. - * @param timeout_ms The timeout after which, if no packet is detected, to + * @param[in] timeout_ms The timeout after which, if no packet is detected, to * abort scanning. - * @param baudrate The baudrate of the serial port. This parameter is not + * @param[in] baudrate The baudrate of the serial port. This parameter is not * critical, but it helps fine tune the serial port polling * delay. * - * @return SR_OK if a valid packet is found within the given timeout, - * SR_ERR upon failure. + * @retval SR_OK Valid packet was found within the given timeout + * @retval SR_ERR Failure. */ SR_PRIV int serial_stream_detect(struct sr_serial_dev_inst *serial, uint8_t *buf, size_t *buflen, diff --git a/hardware/norma-dmm/protocol.c b/hardware/norma-dmm/protocol.c index 45546ab0..207d1690 100644 --- a/hardware/norma-dmm/protocol.c +++ b/hardware/norma-dmm/protocol.c @@ -70,7 +70,7 @@ SR_PRIV int xgittoint(char xgit) } /** - * Process received line. It consists of 20 hex digits + \r\n, + * Process received line. It consists of 20 hex digits + \\r\\n, * e.g. '08100400018100400000'. */ static void nma_process_line(const struct sr_dev_inst *sdi) diff --git a/libsigrok-internal.h b/libsigrok-internal.h index cb4fd3fe..d19f3670 100644 --- a/libsigrok-internal.h +++ b/libsigrok-internal.h @@ -17,6 +17,10 @@ * along with this program. If not, see . */ +/** @file + * @internal + */ + #ifndef LIBSIGROK_SIGROK_INTERNAL_H #define LIBSIGROK_SIGROK_INTERNAL_H @@ -60,10 +64,11 @@ struct sr_context { }; #ifdef HAVE_LIBUSB_1_0 +/** USB device instance */ struct sr_usb_dev_inst { - uint8_t bus; - uint8_t address; - struct libusb_device_handle *devhdl; + uint8_t bus; /**< USB bus */ + uint8_t address; /**< Device address on USB bus */ + struct libusb_device_handle *devhdl; /**< libusb device handle */ }; #endif @@ -72,10 +77,10 @@ struct sr_usb_dev_inst { #define SERIAL_PARITY_EVEN SP_PARITY_EVEN #define SERIAL_PARITY_ODD SP_PARITY_ODD struct sr_serial_dev_inst { - char *port; - char *serialcomm; + char *port; /**< Port name, e.g. '/dev/tty42'. */ + char *serialcomm; /**< Comm params for serial_set_paramstr(). */ int nonblocking; - struct sp_port *data; + struct sp_port *data; /**< libserialport port handle */ }; #endif @@ -86,7 +91,7 @@ struct sr_usbtmc_dev_inst { /* Private driver context. */ struct drv_context { - struct sr_context *sr_ctx; + struct sr_context *sr_ctx; /**< sigrok context */ GSList *instances; }; @@ -164,8 +169,9 @@ struct sr_session { * an async fashion. We need to make sure the session is stopped from * within the session thread itself. */ - GMutex stop_mutex; + GMutex stop_mutex; /**< Mutex protecting access to abort_session. */ gboolean abort_session; + /**< Abort current session. See sr_session_stop(). */ }; SR_PRIV int sr_session_send(const struct sr_dev_inst *sdi, diff --git a/libsigrok.h b/libsigrok.h index 5589bdc1..86995690 100644 --- a/libsigrok.h +++ b/libsigrok.h @@ -41,9 +41,9 @@ extern "C" { * * The correct way to get/use the libsigrok API functions is: * - * @code{.c} - * #include - * @endcode + @code{.c} + #include + @endcode */ /* @@ -131,6 +131,7 @@ enum { #define SR_PRIV #endif +/** Type definition for callback function for data reception. */ typedef int (*sr_receive_data_callback_t)(int fd, int revents, void *cb_data); /** Data types used by sr_config_info(). */ @@ -148,17 +149,18 @@ enum { /** Value for sr_datafeed_packet.type. */ enum { - SR_DF_HEADER = 10000, - SR_DF_END, - SR_DF_META, - SR_DF_TRIGGER, - SR_DF_LOGIC, - SR_DF_ANALOG, - SR_DF_FRAME_BEGIN, - SR_DF_FRAME_END, + SR_DF_HEADER = 10000, /**< Payload is sr_datafeed_header. */ + SR_DF_END, /**< End of stream (no further data). */ + SR_DF_META, /**< Payload is struct sr_datafeed_meta */ + SR_DF_TRIGGER, /**< The trigger matched at this point in the data feed. + No payload. */ + SR_DF_LOGIC, /**< Payload is struct sr_datafeed_logic. */ + SR_DF_ANALOG, /**< Payload is struct sr_datafeed_analog. */ + SR_DF_FRAME_BEGIN, /**< Beginning of frame. No payload. */ + SR_DF_FRAME_END, /**< End of frame. No payload. */ }; -/** Values for sr_datafeed_analog.mq. */ +/** Measured quantity, sr_datafeed_analog.mq. */ enum { SR_MQ_VOLTAGE = 10000, SR_MQ_CURRENT, @@ -166,37 +168,34 @@ enum { SR_MQ_CAPACITANCE, SR_MQ_TEMPERATURE, SR_MQ_FREQUENCY, - SR_MQ_DUTY_CYCLE, - SR_MQ_CONTINUITY, + SR_MQ_DUTY_CYCLE, /**< Duty cycle, e.g. on/off ratio. */ + SR_MQ_CONTINUITY, /**< Continuity test. */ SR_MQ_PULSE_WIDTH, SR_MQ_CONDUCTANCE, - /** Electrical power, usually in W, or dBm. */ - SR_MQ_POWER, - /** Gain (a transistor's gain, or hFE, for example). */ - SR_MQ_GAIN, + SR_MQ_POWER, /**< Electrical power, usually in W, or dBm. */ + SR_MQ_GAIN, /**< Gain (a transistor's gain, or hFE, for example). */ /** Logarithmic representation of sound pressure relative to a * reference value. */ SR_MQ_SOUND_PRESSURE_LEVEL, - SR_MQ_CARBON_MONOXIDE, - SR_MQ_RELATIVE_HUMIDITY, + SR_MQ_CARBON_MONOXIDE, /**< Carbon monoxide level */ + SR_MQ_RELATIVE_HUMIDITY,/**< Humidity */ SR_MQ_TIME, /**< Time */ }; -/** Values for sr_datafeed_analog.unit. */ +/** Unit of measured quantity, sr_datafeed_analog.unit. */ enum { - SR_UNIT_VOLT = 10000, - SR_UNIT_AMPERE, - SR_UNIT_OHM, - SR_UNIT_FARAD, - SR_UNIT_KELVIN, - SR_UNIT_CELSIUS, - SR_UNIT_FAHRENHEIT, - SR_UNIT_HERTZ, - SR_UNIT_PERCENTAGE, - SR_UNIT_BOOLEAN, - SR_UNIT_SECOND, - /** Unit of conductance, the inverse of resistance. */ - SR_UNIT_SIEMENS, + SR_UNIT_VOLT = 10000, /**< Volt */ + SR_UNIT_AMPERE, /**< Ampere (current). */ + SR_UNIT_OHM, /**< Ohm (resistance). */ + SR_UNIT_FARAD, /**< Farad (capacity). */ + SR_UNIT_KELVIN, /**< Kelvin (temperature). */ + SR_UNIT_CELSIUS, /**< Degrees Celsius (temperature). */ + SR_UNIT_FAHRENHEIT, /**< Degrees Fahrenheit (temperature). */ + SR_UNIT_HERTZ, /**< Hertz (frequency, 1/s, [Hz]). */ + SR_UNIT_PERCENTAGE, /**< Percent value. */ + SR_UNIT_BOOLEAN, /**< Boolean value. */ + SR_UNIT_SECOND, /**< Time in seconds. */ + SR_UNIT_SIEMENS, /**< Unit of conductance, the inverse of resistance. */ /** * An absolute measurement of power, in decibels, referenced to * 1 milliwatt (dBu). @@ -218,10 +217,10 @@ enum { * represented as the fraction of number of particles of the substance. */ SR_UNIT_CONCENTRATION, - SR_UNIT_REVOLUTIONS_PER_MINUTE, - SR_UNIT_VOLT_AMPERE, - SR_UNIT_WATT, - SR_UNIT_WATT_HOUR, + SR_UNIT_REVOLUTIONS_PER_MINUTE, /**< Revolutions per minute. */ + SR_UNIT_VOLT_AMPERE, /**< Apparent power [VA]. */ + SR_UNIT_WATT, /**< Real power [W]. */ + SR_UNIT_WATT_HOUR, /**< Consumption [Wh]. */ }; /** Values for sr_datafeed_analog.flags. */ @@ -272,37 +271,44 @@ enum { SR_MQFLAG_DURATION = 0x20000, }; +/** sigrok context (opaque). @see sr_init(), sr_exit(). */ struct sr_context; +/** Packet in a sigrok data feed. */ struct sr_datafeed_packet { uint16_t type; const void *payload; }; +/** Header of a sigrok data feed. */ struct sr_datafeed_header { int feed_version; struct timeval starttime; }; +/** Datafeed payload for type SR_DF_META. */ struct sr_datafeed_meta { GSList *config; }; +/** Logic datafeed payload for type SR_DF_LOGIC. */ struct sr_datafeed_logic { uint64_t length; uint16_t unitsize; void *data; }; +/** Analog datafeed payload for type SR_DF_ANALOG. */ struct sr_datafeed_analog { /** The probes for which data is included in this packet. */ GSList *probes; - int num_samples; - /** Measured quantity (voltage, current, temperature, and so on). */ + int num_samples; /**< Number of samples in data */ + /** Measured quantity (voltage, current, temperature, and so on). + * Use SR_MQ_VOLTAGE, ... */ int mq; - /** Unit in which the MQ is measured. */ + /** Unit in which the MQ is measured. Use SR_UNIT_VOLT, ... */ int unit; - /** Bitmap with extra information about the MQ. */ + /** Bitmap with extra information about the MQ. Use SR_MQFLAG_AC, ... */ uint64_t mqflags; /** The analog value(s). The data is interleaved according to * the probes list. */ @@ -324,6 +330,7 @@ struct sr_input { void *internal; }; +/** Input (file) format driver. */ struct sr_input_format { /** The unique ID for this input format. Must not be NULL. */ char *id; @@ -337,9 +344,10 @@ struct sr_input_format { /** * Check if this input module can load and parse the specified file. * - * @param filename The name (and path) of the file to check. + * @param[in] filename The name (and path) of the file to check. * - * @return TRUE if this module knows the format, FALSE if it doesn't. + * @retval TRUE This module knows the format. + * @retval FALSE This module does not know the format. */ int (*format_match) (const char *filename); @@ -349,9 +357,10 @@ struct sr_input_format { * @param in A pointer to a valid 'struct sr_input' that the caller * has to allocate and provide to this function. It is also * the responsibility of the caller to free it later. - * @param filename The name (and path) of the file to use. + * @param[in] filename The name (and path) of the file to use. * - * @return SR_OK upon success, a negative error code upon failure. + * @retval SR_OK Success + * @retval other Negative error code. */ int (*init) (struct sr_input *in, const char *filename); @@ -372,7 +381,8 @@ struct sr_input_format { * the responsibility of the caller to free it later. * @param filename The name (and path) of the file to use. * - * @return SR_OK upon success, a negative error code upon failure. + * @retval SR_OK Success + * @retval other Negative error code. */ int (*loadfile) (struct sr_input *in, const char *filename); }; @@ -408,6 +418,7 @@ struct sr_output { void *internal; }; +/** Output (file) format driver. */ struct sr_output_format { /** * A unique ID for this output format. Must not be NULL. @@ -427,7 +438,7 @@ struct sr_output_format { */ char *description; - int df_type; + int df_type; /**< Datafeed type, SR_DF_HEADER, etc. */ /** * This function is called once, at the beginning of an output stream. @@ -441,7 +452,8 @@ struct sr_output_format { * * @param o Pointer to the respective 'struct sr_output'. * - * @return SR_OK upon success, a negative error code otherwise. + * @retval SR_OK Success + * @retval other Negative error code. */ int (*init) (struct sr_output *o); @@ -473,7 +485,8 @@ struct sr_output_format { * @param data_out Pointer to the allocated output buffer. * @param length_out Length (in bytes) of the output. * - * @return SR_OK upon success, a negative error code otherwise. + * @retval SR_OK Success + * @retval other Negative error code. */ int (*data) (struct sr_output *o, const uint8_t *data_in, uint64_t length_in, uint8_t **data_out, @@ -504,7 +517,8 @@ struct sr_output_format { * @param data_out Pointer to the allocated output buffer. * @param length_out Length (in bytes) of the output. * - * @return SR_OK upon success, a negative error code otherwise. + * @retval SR_OK Success + * @retval other Negative error code. */ int (*event) (struct sr_output *o, int event_type, uint8_t **data_out, uint64_t *length_out); @@ -524,7 +538,8 @@ struct sr_output_format { * @param out A pointer where a GString * should be stored if * the module generates output, or NULL if not. * - * @return SR_OK upon success, a negative error code otherwise. + * @retval SR_OK Success + * @retval other Negative error code. */ int (*receive) (struct sr_output *o, const struct sr_dev_inst *sdi, const struct sr_datafeed_packet *packet, GString **out); @@ -534,23 +549,26 @@ struct sr_output_format { * the output module, and can be used to free any internal * resources the module may keep. * - * @return SR_OK upon success, a negative error code otherwise. + * @retval SR_OK Success + * @retval other Negative error code. */ int (*cleanup) (struct sr_output *o); }; +/** Constants for probe type. */ enum { - SR_PROBE_LOGIC = 10000, - SR_PROBE_ANALOG, + SR_PROBE_LOGIC = 10000, /**< Probe type is logic probe. */ + SR_PROBE_ANALOG, /**< Probe type is analog probe. */ }; +/** Information on single probe. */ struct sr_probe { - /* The index field will go: use g_slist_length(sdi->probes) instead. */ - int index; - int type; - gboolean enabled; - char *name; - char *trigger; + int index; /**< Number of probe, starting at 0. @deprecated The + index field will go: use g_slist_length(sdi->probes) instead. */ + int type; /**< Probe type (SR_PROBE_LOGIC, ...) */ + gboolean enabled; /**< Is this probe enabled? */ + char *name;/**< Name of probe. */ + char *trigger;/**< Trigger string, format like used by sigrok-cli */ }; /** Structure for groups of probes that have common properties. */ @@ -563,19 +581,22 @@ struct sr_probe_group { void *priv; }; +/** Used for setting or getting value of a config item. */ struct sr_config { - int key; - GVariant *data; + int key; /**< Config key like SR_CONF_CONN, etc. */ + GVariant *data; /**< Key-specific data. */ }; +/** Information about a config key. */ struct sr_config_info { - int key; - int datatype; - char *id; - char *name; - char *description; + int key; /**< Config key like SR_CONF_CONN, etc. */ + int datatype; /**< Data type like SR_T_CHAR, etc. */ + char *id; /**< Id string, e.g. "serialcomm". */ + char *name; /**< Name, e.g. "Serial communication". */ + char *description; /**< Verbose description (unused currently). */ }; +/** Constants for device classes */ enum { /*--- Device classes ------------------------------------------------*/ @@ -782,22 +803,24 @@ enum { SR_CONF_DATALOG, }; +/** @private + * Device instance data + */ struct sr_dev_inst { - struct sr_dev_driver *driver; - int index; - int status; - int inst_type; - char *vendor; - char *model; - char *version; - GSList *probes; - /* List of sr_probe_group structs */ - GSList *probe_groups; - void *conn; - void *priv; + struct sr_dev_driver *driver; /**< Device driver. */ + int index; /**< Index of device in driver. */ + int status; /**< Device instance status. SR_ST_NOT_FOUND, etc. */ + int inst_type; /**< Device instance type. SR_INST_USB, etc. */ + char *vendor; /**< Device vendor. */ + char *model; /**< Device model. */ + char *version; /**< Device version. */ + GSList *probes; /**< List of probes. */ + GSList *probe_groups; /**< List of sr_probe_group structs */ + void *conn; /**< Device instance connection data (used?) */ + void *priv; /**< Device instance private data (used?) */ }; -/** Types of device instances (sr_dev_inst). */ +/** Types of device instance, struct sr_dev_inst.type */ enum { /** Device instance type for USB devices. */ SR_INST_USB = 10000, @@ -807,7 +830,7 @@ enum { SR_INST_SCPI, }; -/** Device instance status. */ +/** Device instance status, struct sr_dev_inst.status */ enum { /** The device instance was not found. */ SR_ST_NOT_FOUND = 10000, @@ -821,15 +844,16 @@ enum { SR_ST_STOPPING, }; +/** Device driver data */ struct sr_dev_driver { /* Driver-specific */ - char *name; - char *longname; - int api_version; - int (*init) (struct sr_context *sr_ctx); - int (*cleanup) (void); - GSList *(*scan) (GSList *options); - GSList *(*dev_list) (void); + char *name; /**< Driver name */ + char *longname; /**< Long name, e.g. device name. */ + int api_version; /**< API version (currently 1). */ + int (*init) (struct sr_context *sr_ctx); /**< Init driver */ + int (*cleanup) (void); /**< Free driver */ + GSList *(*scan) (GSList *options); /**< Scan for devices */ + GSList *(*dev_list) (void); /**< Get device list */ int (*dev_clear) (void); int (*config_get) (int id, GVariant **data, const struct sr_dev_inst *sdi, @@ -842,15 +866,15 @@ struct sr_dev_driver { const struct sr_probe_group *probe_group); /* Device-specific */ - int (*dev_open) (struct sr_dev_inst *sdi); - int (*dev_close) (struct sr_dev_inst *sdi); + int (*dev_open) (struct sr_dev_inst *sdi); /**< Open device */ + int (*dev_close) (struct sr_dev_inst *sdi); /**< Close device */ int (*dev_acquisition_start) (const struct sr_dev_inst *sdi, - void *cb_data); + void *cb_data); /**< Start data aquisition. */ int (*dev_acquisition_stop) (struct sr_dev_inst *sdi, - void *cb_data); + void *cb_data); /**< Stop data aquisition. */ /* Dynamic */ - void *priv; + void *priv; /**< Device driver private data */ }; /** diff --git a/session.c b/session.c index 1cf4170e..2725d6e9 100644 --- a/session.c +++ b/session.c @@ -74,7 +74,8 @@ struct sr_session *session; * @todo Should it use the file-global "session" variable or take an argument? * The same question applies to all the other session functions. * - * @return A pointer to the newly allocated session, or NULL upon errors. + * @retval NULL Error. + * @retval other A pointer to the newly allocated session-> */ SR_API struct sr_session *sr_session_new(void) { @@ -93,10 +94,10 @@ SR_API struct sr_session *sr_session_new(void) /** * Destroy the current session. - * * This frees up all memory used by the session. * - * @return SR_OK upon success, SR_ERR_BUG if no session exists. + * @retval SR_OK Success. + * @retval SR_ERR_BUG No session exists. */ SR_API int sr_session_destroy(void) { @@ -123,7 +124,8 @@ SR_API int sr_session_destroy(void) * The session itself (i.e., the struct sr_session) is not free'd and still * exists after this function returns. * - * @return SR_OK upon success, SR_ERR_BUG if no session exists. + * @retval SR_OK Success. + * @retval SR_ERR_BUG No session exists. */ SR_API int sr_session_dev_remove_all(void) { @@ -145,7 +147,9 @@ SR_API int sr_session_dev_remove_all(void) * be NULL. Also, sdi->driver and sdi->driver->dev_open must * not be NULL. * - * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments. + * @retval SR_OK Success. + * @retval SR_ERR_ARG Invalid argument. + * @retval SR_ERR_BUG No session exists. */ SR_API int sr_session_dev_add(const struct sr_dev_inst *sdi) { @@ -200,7 +204,8 @@ SR_API int sr_session_dev_add(const struct sr_dev_inst *sdi) * The list must be freed by the caller, but not the * elements pointed to. * - * @return SR_OK upon success, SR_ERR upon invalid arguments. + * @retval SR_OK Success. + * @retval SR_ERR Invalid argument. */ SR_API int sr_session_dev_list(GSList **devlist) { @@ -218,7 +223,8 @@ SR_API int sr_session_dev_list(GSList **devlist) /** * Remove all datafeed callbacks in the current session. * - * @return SR_OK upon success, SR_ERR_BUG if no session exists. + * @retval SR_OK Success. + * @retval SR_ERR_BUG No session exists. */ SR_API int sr_session_datafeed_callback_remove_all(void) { @@ -240,7 +246,8 @@ SR_API int sr_session_datafeed_callback_remove_all(void) * Must not be NULL. * @param cb_data Opaque pointer passed in by the caller. * - * @return SR_OK upon success, SR_ERR_BUG if no session exists. + * @retval SR_OK Success. + * @retval SR_ERR_BUG No session exists. */ SR_API int sr_session_datafeed_callback_add(sr_datafeed_callback_t cb, void *cb_data) { @@ -282,7 +289,8 @@ SR_API int sr_session_datafeed_callback_add(sr_datafeed_callback_t cb, void *cb_ * If FALSE, all sources have their callback run, regardless * of file descriptor or timeout status. * - * @return SR_OK upon success, SR_ERR on errors. + * @retval SR_OK Success. + * @retval SR_ERR Error occured. */ static int sr_session_iteration(gboolean block) { @@ -327,7 +335,8 @@ static int sr_session_iteration(gboolean block) * * There can only be one session at a time. * - * @return SR_OK upon success, SR_ERR upon errors. + * @retval SR_OK Success. + * @retval SR_ERR Error occured. */ SR_API int sr_session_start(void) { @@ -367,7 +376,8 @@ SR_API int sr_session_start(void) /** * Run the session. * - * @return SR_OK upon success, SR_ERR_BUG upon errors. + * @retval SR_OK Success. + * @retval SR_ERR_BUG Error occured. */ SR_API int sr_session_run(void) { @@ -410,7 +420,8 @@ SR_API int sr_session_run(void) * This must be called from within the session thread, to prevent freeing * resources that the session thread will try to use. * - * @return SR_OK upon success, SR_ERR_BUG if no session exists. + * @retval SR_OK Success. + * @retval SR_ERR_BUG No session exists. * * @private */ @@ -449,7 +460,8 @@ SR_PRIV int sr_session_stop_sync(void) * to wait for the session thread to return before assuming that the session is * completely decommissioned. * - * @return SR_OK upon success, SR_ERR_BUG if no session exists. + * @retval SR_OK Success. + * @retval SR_ERR_BUG No session exists. */ SR_API int sr_session_stop(void) { @@ -518,7 +530,8 @@ static void datafeed_dump(const struct sr_datafeed_packet *packet) * @param sdi TODO. * @param packet The datafeed packet to send to the session bus. * - * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments. + * @retval SR_OK Success. + * @retval SR_ERR_ARG Invalid argument. * * @private */ @@ -552,13 +565,15 @@ SR_PRIV int sr_session_send(const struct sr_dev_inst *sdi, * Add an event source for a file descriptor. * * @param pollfd The GPollFD. - * @param timeout Max time to wait before the callback is called, ignored if 0. + * @param[in] timeout Max time to wait before the callback is called, + * ignored if 0. * @param cb Callback function to add. Must not be NULL. * @param cb_data Data for the callback function. Can be NULL. * @param poll_object TODO. * - * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or - * SR_ERR_MALLOC upon memory allocation errors. + * @retval SR_OK Success. + * @retval SR_ERR_ARG Invalid argument. + * @retval SR_ERR_MALLOC Memory allocation error. */ static int _sr_session_source_add(GPollFD *pollfd, int timeout, sr_receive_data_callback_t cb, void *cb_data, gintptr poll_object) @@ -612,8 +627,9 @@ static int _sr_session_source_add(GPollFD *pollfd, int timeout, * @param cb Callback function to add. Must not be NULL. * @param cb_data Data for the callback function. Can be NULL. * - * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or - * SR_ERR_MALLOC upon memory allocation errors. + * @retval SR_OK Success. + * @retval SR_ERR_ARG Invalid argument. + * @retval SR_ERR_MALLOC Memory allocation error. */ SR_API int sr_session_source_add(int fd, int events, int timeout, sr_receive_data_callback_t cb, void *cb_data) @@ -634,8 +650,9 @@ SR_API int sr_session_source_add(int fd, int events, int timeout, * @param cb Callback function to add. Must not be NULL. * @param cb_data Data for the callback function. Can be NULL. * - * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or - * SR_ERR_MALLOC upon memory allocation errors. + * @retval SR_OK Success. + * @retval SR_ERR_ARG Invalid argument. + * @retval SR_ERR_MALLOC Memory allocation error. */ SR_API int sr_session_source_add_pollfd(GPollFD *pollfd, int timeout, sr_receive_data_callback_t cb, void *cb_data) @@ -653,8 +670,9 @@ SR_API int sr_session_source_add_pollfd(GPollFD *pollfd, int timeout, * @param cb Callback function to add. Must not be NULL. * @param cb_data Data for the callback function. Can be NULL. * - * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or - * SR_ERR_MALLOC upon memory allocation errors. + * @retval SR_OK Success. + * @retval SR_ERR_ARG Invalid argument. + * @retval SR_ERR_MALLOC Memory allocation error. */ SR_API int sr_session_source_add_channel(GIOChannel *channel, int events, int timeout, sr_receive_data_callback_t cb, void *cb_data) @@ -676,11 +694,12 @@ SR_API int sr_session_source_add_channel(GIOChannel *channel, int events, * * @todo Add more error checks and logging. * - * @param channel The channel for which the source should be removed. + * @param poll_object The channel for which the source should be removed. * - * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or - * SR_ERR_MALLOC upon memory allocation errors, SR_ERR_BUG upon - * internal errors. + * @retval SR_OK Success + * @retval SR_ERR_ARG Invalid arguments + * @retval SR_ERR_MALLOC Memory allocation error + * @retval SR_ERR_BUG Internal error */ static int _sr_session_source_remove(gintptr poll_object) { @@ -734,9 +753,10 @@ static int _sr_session_source_remove(gintptr poll_object) * * @param fd The file descriptor for which the source should be removed. * - * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or - * SR_ERR_MALLOC upon memory allocation errors, SR_ERR_BUG upon - * internal errors. + * @retval SR_OK Success + * @retval SR_ERR_ARG Invalid argument + * @retval SR_ERR_MALLOC Memory allocation error. + * @retval SR_ERR_BUG Internal error. */ SR_API int sr_session_source_remove(int fd) { @@ -762,9 +782,10 @@ SR_API int sr_session_source_remove_pollfd(GPollFD *pollfd) * * @param channel The channel for which the source should be removed. * - * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or - * SR_ERR_MALLOC upon memory allocation errors, SR_ERR_BUG upon - * internal errors. + * @retval SR_OK Success. + * @retval SR_ERR_ARG Invalid argument. + * @retval SR_ERR_MALLOC Memory allocation error. + * @return SR_ERR_BUG Internal error. */ SR_API int sr_session_source_remove_channel(GIOChannel *channel) { diff --git a/std.c b/std.c index 7dc020b9..9fac390d 100644 --- a/std.c +++ b/std.c @@ -18,6 +18,11 @@ * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */ +/** \file + * Standard API helper functions. + * @internal + */ + #include #include "libsigrok.h" #include "libsigrok-internal.h" @@ -32,7 +37,7 @@ * * @param sr_ctx The libsigrok context to assign. * @param di The driver instance to use. - * @param prefix A driver-specific prefix string used for log messages. + * @param[in] prefix A driver-specific prefix string used for log messages. * * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or * SR_ERR_MALLOC upon memory allocation errors.