From 2a4f2df2244018f525d23805f9fbdfa3f21b4570 Mon Sep 17 00:00:00 2001 From: Robin Krahl Date: Wed, 16 Jan 2019 19:17:17 +0100 Subject: Add a doc target that generates C API documentation Doxygen is used generate the C API documentation. The Doxygen configuration is stored in the Doxygen.in file (that is processed by CMake). To generate the documentation, run make doc in the build directory. --- CMakeLists.txt | 9 +++++++++ Doxyfile.in | 17 +++++++++++++++++ 2 files changed, 26 insertions(+) create mode 100644 Doxyfile.in diff --git a/CMakeLists.txt b/CMakeLists.txt index 1004baf..f7d98a3 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 -- cgit v1.2.3 From 5d79387008dc81f9504103259a21f23962a5a966 Mon Sep 17 00:00:00 2001 From: Robin Krahl Date: Wed, 16 Jan 2019 19:23:30 +0100 Subject: Add a \file doc comment to libnitrokey Doxygen does not include top-level functions unless the file is documented. Therefore we have to add a \file doc comment so that the functions show up in the Doxygen output. --- NK_C_API.h | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/NK_C_API.h b/NK_C_API.h index b1bdf1e..289eaee 100644 --- a/NK_C_API.h +++ b/NK_C_API.h @@ -33,6 +33,12 @@ #define NK_C_API #endif +/** + * \file + * + * C API for libnitrokey + */ + #ifdef __cplusplus extern "C" { #endif -- cgit v1.2.3 From 2491bcac250ea7036a4f39b06f4c8dcefea1650b Mon Sep 17 00:00:00 2001 From: Robin Krahl Date: Wed, 16 Jan 2019 19:41:58 +0100 Subject: Add \mainpage to the C API documentation The main page contains a reference to the header containing all functions of the C API and a short example of how to use it. --- NK_C_API.h | 46 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/NK_C_API.h b/NK_C_API.h index 289eaee..c803ef1 100644 --- a/NK_C_API.h +++ b/NK_C_API.h @@ -37,6 +37,52 @@ * \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 + * #include + * #include + * + * 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 -- cgit v1.2.3 From af8ee6d30ac8ae45cf440c6bc2e03a873e3db584 Mon Sep 17 00:00:00 2001 From: Robin Krahl Date: Wed, 16 Jan 2019 19:46:59 +0100 Subject: Update readme for `make doc` --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 0b6b8d9..8390fb6 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 [include/NitrokeyManager.h](include/NitrokeyManager.h) (C++ API). All devices' commands are listed along with packet format in [include/stick10_commands.h](include/stick10_commands.h) and [include/stick20_commands.h](include/stick20_commands.h) respectively for Nitrokey Pro and Nitrokey Storage products. # Tests -- cgit v1.2.3