Merge branch 'pr_148'

Generate documentation for C API using Doxygen

Fixes #148

4 files changed, 79 insertions, 1 deletions

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 57ed28f..7ba6f9a 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -233,3 +233,12 @@ set (CPACK_RESOURCE_FILE_LICENSE
         "${CMAKE_CURRENT_SOURCE_DIR}/LICENSE")
 set (CPACK_PACKAGE_VERSION "${PROJECT_VERSION}")
 include (CPack)
+
+# Build Doxygen documentation for the C API
+find_package(Doxygen)
+if (DOXYGEN_FOUND)
+    configure_file(${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile @ONLY)
+    add_custom_target(doc ${DOXYGEN_EXECUTABLE} Doxyfile
+        WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+        COMMENT "Generating C API documentation with Doxygen" VERBATIM)
+endif(DOXYGEN_FOUND)
diff --git a/Doxyfile.in b/Doxyfile.in
new file mode 100644
index 0000000..9211df1
--- /dev/null
+++ b/Doxyfile.in
@@ -0,0 +1,17 @@
+# For better readability, the documentation and default settings are removed
+# from this file.  For more information on the Doxygen configuration, generate
+# a new Doxyfile using `doxygen -g` or have a look at the Doxygen manual at
+# http://www.doxygen.nl/manual/config.html
+#
+# This file is processed by CMake.  To generate the documentation, run `make
+# doc` in the build directory.
+
+PROJECT_NAME           = "@CMAKE_PROJECT_NAME@"
+PROJECT_NUMBER         = "@PROJECT_VERSION@"
+PROJECT_BRIEF          =
+OUTPUT_DIRECTORY       = doc
+STRIP_FROM_PATH        = @CMAKE_CURRENT_SOURCE_DIR@
+JAVADOC_AUTOBRIEF      = YES
+OPTIMIZE_OUTPUT_FOR_C  = YES
+WARN_NO_PARAMDOC       = YES
+INPUT                  = @CMAKE_CURRENT_SOURCE_DIR@/NK_C_API.h
diff --git a/NK_C_API.h b/NK_C_API.h
index a6b3072..47b2567 100644
--- a/NK_C_API.h
+++ b/NK_C_API.h
@@ -33,6 +33,58 @@
 #define NK_C_API
 #endif
 
+/**
+ * \file
+ *
+ * C API for libnitrokey
+ *
+ * \mainpage
+ *
+ * **libnitrokey** provides access to Nitrokey Pro and Nitrokey Storage devices.
+ * This documentation describes libnitrokey’s C API.  For a list of the
+ * available functions, see the NK_C_API.h file.
+ *
+ * \section getting_started Example
+ *
+ * \code{.c}
+ * #include <stdio.h>
+ * #include <stdlib.h>
+ * #include <libnitrokey/NK_C_API.h>
+ *
+ * int main(void)
+ * {
+ *         if (NK_login_auto() != 1) {
+ *                 fprintf(stderr, "No Nitrokey found.\n");
+ *                 return 1;
+ *         }
+ *
+ *         NK_device_model model = NK_get_device_model();
+ *         printf("Connected to ");
+ *         switch (model) {
+ *         case NK_PRO:
+ *                 printf("a Nitrokey Pro");
+ *                 break;
+ *         case NK_STORAGE:
+ *                 printf("a Nitrokey Storage");
+ *                 break;
+ *         default:
+ *                 printf("an unsupported Nitrokey");
+ *                 break;
+ *         }
+ *
+ *         char* serial_number = NK_device_serial_number();
+ *         if (serial_number)
+ *             printf(" with serial number %s\n", serial_number);
+ *         else
+ *             printf(" -- could not query serial number!\n");
+ *         free(serial_number);
+ *
+ *         NK_logout();
+ *         return 0;
+ * }
+ * \endcode
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
diff --git a/README.md b/README.md
index be820fc..a3683c0 100644
--- a/README.md
+++ b/README.md
@@ -163,7 +163,7 @@ In case  no devices are connected, a friendly message will be printed.
 All available functions for C and Python are listed in [NK_C_API.h](NK_C_API.h). Please check `Documentation` section below.
 
 ## Documentation
-The documentation of C API is included in the sources (could be  generated with doxygen if requested).
+The documentation of C API is included in the sources (can be generated with `make doc` if Doxygen is installed).
 Please check [NK_C_API.h](NK_C_API.h) (C API) for high level commands and [libnitrokey/NitrokeyManager.h](libnitrokey/NitrokeyManager.h) (C++ API). All devices' commands are listed along with packet format in [libnitrokey/stick10_commands.h](libnitrokey/stick10_commands.h) and [libnitrokey/stick20_commands.h](libnitrokey/stick20_commands.h) respectively for Nitrokey Pro and Nitrokey Storage products.
 
 # Tests