add Doxygen docs

4 files changed, 54 insertions, 4 deletions

diff --git a/CMakeLists.txt b/CMakeLists.txt
index b4b277b..2f6d476 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -23,3 +23,12 @@ if(WINAPI_UTF8_TESTS)
 endif()
 
 install(FILES LICENSE.txt DESTINATION share)
+
+find_package(Doxygen)
+if(DOXYGEN_FOUND)
+    set(DOXYGEN_USE_MDFILE_AS_MAINPAGE README.md)
+    set(DOXYGEN_SOURCE_BROWSER YES)
+    set(DOXYGEN_INCLUDE_GRAPH NO)
+    set(DOXYGEN_INCLUDED_BY_GRAPH NO)
+    doxygen_add_docs(docs README.md ${winapi_utf8_include} ${winapi_utf8_src})
+endif()
diff --git a/Makefile b/Makefile
index 61f1cc1..163436d 100644
--- a/Makefile
+++ b/Makefile
@@ -83,6 +83,15 @@ install: build
 test:
 	cd -- '$(call escape,$(cmake_dir))' && ctest -C '$(call escape,$(CONFIGURATION))' --verbose
 
+xdg-open := $(shell command -v xdg-open 2> /dev/null)
+
+.PHONY: docs
+docs:
+	cmake --build '$(call escape,$(cmake_dir))' --target docs
+ifdef xdg-open
+	xdg-open '$(call escape,$(cmake_dir))/html/index.html'
+endif
+
 clang-tidy := run-clang-tidy
 ifeq (1,$(shell test -e /usr/share/clang/run-clang-tidy.py && echo 1))
 clang-tidy := /usr/share/clang/run-clang-tidy.py
diff --git a/README.md b/README.md
index c514822..a577906 100644
--- a/README.md
+++ b/README.md
@@ -20,6 +20,13 @@ directory (defaults to building with MinGW-w64):
     make build
     make test
 
+Documentation
+-------------
+
+Build & display the documentation using
+
+    make docs
+
 License
 -------
 
diff --git a/include/winapi/utf8.hpp b/include/winapi/utf8.hpp
index 9469fd7..c5ec9ac 100644
--- a/include/winapi/utf8.hpp
+++ b/include/winapi/utf8.hpp
@@ -3,6 +3,11 @@
 // For details, see https://github.com/egor-tensin/winapi-utf8.
 // Distributed under the MIT License.
 
+/**
+ * @file
+ * @brief UTF-8 <-> UTF-16 conversion functions
+ */
+
 #pragma once
 
 #include <cstddef>
@@ -12,17 +17,37 @@
 
 namespace winapi {
 
+/** Convert UTF-8 string to UTF-16. */
 std::wstring widen(const std::string&);
-std::wstring widen(const void*, std::size_t nb);
-
+/**
+ * Convert UTF-8 string to UTF-16.
+ * \param src Pointer to UTF-8 string.
+ * \param nb  Number of bytes pointed to src.
+ */
+std::wstring widen(const void* src, std::size_t nb);
+
+/**
+ * Convert UTF-8 string to UTF-16.
+ * \param src UTF-8 string.
+ */
 template <typename T, typename Alloc = std::allocator<T>>
 std::wstring widen(const std::vector<T, Alloc>& src) {
     return widen(src.data(), src.size() * sizeof(T));
 }
 
+/** Convert UTF-16 string to UTF-8. */
 std::string narrow(const std::wstring&);
-std::string narrow(const void*, std::size_t nb);
-
+/**
+ * Convert UTF-16 string to UTF-8.
+ * \param src Pointer to UTF-16 string.
+ * \param nb  Number of bytes pointed to by src.
+ */
+std::string narrow(const void* src, std::size_t nb);
+
+/**
+ * Convert UTF-16 string to UTF-8.
+ * \param src UTF-16 string.
+ */
 template <typename T, typename Alloc = std::allocator<T>>
 std::string narrow(const std::vector<T, Alloc>& src) {
     return narrow(src.data(), src.size() * sizeof(T));