From: Martin Ling <redacted>
Date: Sun, 5 Jan 2020 03:04:38 +0000 (+0000)
Subject: Integrate examples into Doxygen.
X-Git-Url: https://sigrok.org/gitweb/?p=libserialport.git;a=commitdiff_plain;h=7c8d67efdc711b9ba942a83153200d7185adf929

Integrate examples into Doxygen.
---

diff --git a/Doxyfile b/Doxyfile
index fa6344b..266d1db 100644
--- a/Doxyfile
+++ b/Doxyfile
@@ -821,14 +821,14 @@ EXCLUDE_SYMBOLS        =
 # that contain example code fragments that are included (see the \include
 # command).
 
-EXAMPLE_PATH           =
+EXAMPLE_PATH           = examples
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the
 # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and
 # *.h) to filter out the source-files in the directories. If left blank all
 # files are included.
 
-EXAMPLE_PATTERNS       =
+EXAMPLE_PATTERNS       = *.c
 
 # If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be
 # searched for input files to be used with the \include or \dontinclude commands
diff --git a/libserialport.h.in b/libserialport.h.in
index 8962ef8..7f6b9b9 100644
--- a/libserialport.h.in
+++ b/libserialport.h.in
@@ -59,7 +59,19 @@
  * to restructure things somewhat, or do without some specialised features.
  * For particular notes on porting existing code, see @ref Porting.
  *
- * The following subsections will help explain the principles of the API.
+ * Examples
+ * --------
+ *
+ * Some simple example programs using libserialport are included in the
+ * @c examples directory in the source package:
+ *
+ * - @ref list_ports.c - Getting a list of ports present on the system.
+ * - @ref port_info.c - Getting information on a particular serial port.
+ *
+ * These examples are linked with the API documentation. Each function
+ * in the API reference includes links to where it is used in an example
+ * program, and each appearance of a function in the examples links
+ * to that function's entry in the API reference.
  *
  * Headers
  * -------
@@ -445,6 +457,8 @@ struct sp_event_set {
  *
  * Enumerating the serial ports of a system.
  *
+ * See @ref list_ports.c for a working example of port enumeration.
+ *
  * @{
  */
 
@@ -534,6 +548,8 @@ void sp_free_port_list(struct sp_port **ports);
  *
  * Opening, closing and querying ports.
  *
+ * See @ref port_info.c for a working example of getting port information.
+ *
  * @{
  */
 
@@ -1706,6 +1722,11 @@ const char *sp_get_lib_version_string(void);
 
 /** @} */
 
+/**
+ * @example list_ports.c Getting a list of ports present on the system.
+ * @example port_info.c Getting information on a particular serial port.
+*/
+
 #ifdef __cplusplus
 }
 #endif