doxygen: Add more output format docs.

This is largely taken from the respective wiki page (with some updates
and improvements), which will be removed in favor of the doxygen docs.

libsigrok.h

@@ -368,27 +368,141 @@ struct sr_input_format {
 	int (*loadfile) (struct sr_input *in, const char *filename);
 };
 
+/** Output (file) format struct. */
 struct sr_output {
+	/**
+	 * A pointer to this output format's 'struct sr_output_format'.
+	 * The frontend can use this to call the module's callbacks.
+	 */
 	struct sr_output_format *format;
+
+	/**
+	 * The device for which this output module is creating output. This
+	 * can be used by the module to find out probe names and numbers.
+	 */
 	struct sr_dev_inst *sdi;
+
+	/**
+	 * An optional parameter which the frontend can pass in to the
+	 * output module. How the string is interpreted is entirely up to
+	 * the module.
+	 */
 	char *param;
+
+	/**
+	 * A generic pointer which can be used by the module to keep internal
+	 * state between calls into its callback functions.
+	 *
+	 * For example, the module might store a pointer to a chunk of output
+	 * there, and only flush it when it reaches a certain size.
+	 */
 	void *internal;
 };
 
 struct sr_output_format {
+	/**
+	 * A unique ID for this output format. Must not be NULL.
+	 *
+	 * It can be used by frontends to select this output format for use.
+	 *
+	 * For example, calling sigrok-cli with <code>-O hex</code> will
+	 * select the hexadecimal text output format.
+	 */
 	char *id;
+
+	/**
+	 * A short description of the output format. Must not be NULL.
+	 *
+	 * This can be displayed by frontends, e.g. when selecting the output
+	 * format for saving a file.
+	 */
 	char *description;
+
 	int df_type;
+
+	/**
+	 * This function is called once, at the beginning of an output stream.
+	 *
+	 * The device struct will be available in the output struct passed in,
+	 * as well as the param field -- which may be NULL or an empty string,
+	 * if no parameter was passed.
+	 *
+	 * The module can use this to initialize itself, create a struct for
+	 * keeping state and storing it in the <code>internal</code> field.
+	 *
+	 * @param o Pointer to the respective 'struct sr_output'.
+	 *
+	 * @return SR_OK upon success, a negative error code otherwise.
+	 */
 	int (*init) (struct sr_output *o);
-	/* Obsolete, use recv() instead. */
+
+	/**
+	 * Whenever a chunk of data comes in, it will be passed to the
+	 * output module via this function. The <code>data_in</code> and
+	 * <code>length_in</code> values refers to this data; the module
+	 * must not alter or g_free() this buffer.
+	 *
+	 * The function must allocate a buffer for storing its output, and
+	 * pass along a pointer to this buffer in the <code>data_out</code>
+	 * parameter, as well as storing the length of the buffer in
+	 * <code>length_out</code>. The calling frontend will g_free()
+	 * this buffer when it's done with it.
+	 *
+	 * IMPORTANT: The memory allocation much happen using a glib memory
+	 * allocation call (not a "normal" malloc) since g_free() will be
+	 * used to free the memory!
+	 *
+	 * If there is no output, this function MUST store NULL in the
+	 * <code>data_out</code> parameter, so the caller knows not to try
+	 * and g_free() it.
+	 *
+	 * Note: This API call is obsolete, use recv() instead.
+	 *
+	 * @param o Pointer to the respective 'struct sr_output'.
+	 * @param data_in Pointer to the input data buffer.
+	 * @param length_in Length of the input.
+	 * @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.
+	 */
 	int (*data) (struct sr_output *o, const uint8_t *data_in,
 		     uint64_t length_in, uint8_t **data_out,
 		     uint64_t *length_out);
-	/* Obsolete, use recv() instead. */
+
+	/**
+	 * This function is called when an event occurs in the datafeed
+	 * which the output module may need to be aware of. No data is
+	 * passed in, only the fact that the event occurs. The following
+	 * events can currently be passed in:
+	 *
+	 *  - SR_DF_TRIGGER: At this point in the datafeed, the trigger
+	 *    matched. The output module may mark this in some way, e.g. by
+	 *    plotting a red line on a graph.
+	 *
+	 *  - SR_DF_END: This marks the end of the datafeed. No more calls
+	 *    into the output module will be done, so this is a good time to
+	 *    free up any memory used to keep state, for example.
+	 *
+	 * Any output generated by this function must have a reference to
+	 * it stored in the <code>data_out</code> and <code>length_out</code>
+	 * parameters, or NULL if no output was generated.
+	 *
+	 * Note: This API call is obsolete, use recv() instead.
+	 *
+	 * @param o Pointer to the respective 'struct sr_output'.
+	 * @param event_type Type of event that occured.
+	 * @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.
+	 */
 	int (*event) (struct sr_output *o, int event_type, uint8_t **data_out,
 		      uint64_t *length_out);
+
 	GString *(*recv) (struct sr_output *o, const struct sr_dev_inst *sdi,
 			const struct sr_datafeed_packet *packet);
+
 	int (*cleanup) (struct sr_output *o);
 };
 

output/output.c

@@ -31,6 +31,20 @@
  *
  * Output file/data format handling.
  *
+ * libsigrok supports several output (file) formats, e.g. binary, VCD,
+ * gnuplot, and so on. It provides an output API that frontends can use.
+ * New output formats can be added/implemented in libsigrok without having
+ * to change the frontends at all.
+ *
+ * All output modules are fed data in a stream. Devices that can stream data
+ * into libsigrok live, instead of storing and then transferring the whole
+ * buffer, can thus generate output live.
+ *
+ * Output modules are responsible for allocating enough memory to store
+ * their own output, and passing a pointer to that memory (and length) of
+ * the allocated memory back to the caller. The caller is then expected to
+ * free this memory when finished with it.
+ *
  * @{
  */