include: Add basic documentation for vkd3d_types.h.

This is built on Doxygen. I'm not personally attached to Doxygen, but it was
easy enough to set up and write for, and I've found its compiled HTML to be
reasonably legible.

Note that Doxygen does allow for specifying documentation in external files,
if keeping the documentation out of the header is desired.

Signed-off-by: Zebediah Figura <z.figura12@gmail.com>
Signed-off-by: Henri Verbeet <hverbeet@codeweavers.com>
Signed-off-by: Alexandre Julliard <julliard@winehq.org>

.gitignore

@@ -3,6 +3,8 @@ autom4te.cache
 config.log
 config.status
 configure
+doc
+Doxyfile
 libtool
 Makefile
 Makefile.in

Doxyfile.in

@@ -0,0 +1,17 @@
+# Doxyfile 1.8.18
+
+DOXYFILE_ENCODING      = UTF-8
+PROJECT_NAME           = @PACKAGE_NAME@
+PROJECT_NUMBER         = @PACKAGE_VERSION@
+PROJECT_BRIEF          = "The vkd3d 3D Graphics Library"
+OUTPUT_DIRECTORY       = doc
+JAVADOC_AUTOBRIEF      = YES
+OPTIMIZE_OUTPUT_FOR_C  = YES
+EXTRACT_STATIC         = YES
+
+INPUT                  = @srcdir@/include/vkd3d.h \
+                         @srcdir@/include/vkd3d_shader.h \
+                         @srcdir@/include/vkd3d_types.h \
+                         @srcdir@/include/vkd3d_utils.h
+
+EXCLUDE_SYMBOLS        = VKD3D_FORCE_32_BIT_ENUM

Makefile.am

@@ -282,3 +282,9 @@ endif
 
 .PHONY: crosstest crosstest32 crosstest64
 crosstest: crosstest32 crosstest64
+
+if BUILD_DOC
+@DX_RULES@
+all: doxygen-doc
+CLEANFILES += $(DX_CLEANFILES)
+endif

configure.ac

@@ -29,6 +29,10 @@ AC_PROG_MKDIR_P
 VKD3D_PROG_WIDL(3, 20)
 AS_IF([test "x$WIDL" = "xno"], [AC_MSG_WARN([widl is required to build header files.])])
 
+DX_PS_FEATURE([OFF])
+DX_INIT_DOXYGEN([vkd3d], [Doxyfile], [doc])
+AC_CONFIG_FILES([Doxyfile])
+
 AM_INIT_AUTOMAKE([1.11 foreign silent-rules subdir-objects no-dist-gzip dist-xz -Wall -Werror])
 AM_MAINTAINER_MODE([enable])
 AM_SILENT_RULES([yes])
@@ -129,6 +133,7 @@ dnl Makefiles
 AS_IF([test "x$enable_demos" = "xyes" -a "x$HAVE_XCB" != "xyes"],
       [AC_MSG_ERROR([libxcb is required for demos.])])
 AM_CONDITIONAL([BUILD_DEMOS], [test "x$enable_demos" = "xyes"])
+AM_CONDITIONAL([BUILD_DOC], [test $DX_FLAG_doc = 1])
 AM_CONDITIONAL([BUILD_TESTS], [test "x$enable_tests" != "xno"])
 AM_CONDITIONAL([HAVE_WIDL], [test "x$WIDL" != "xno"])
 AM_CONDITIONAL([HAVE_CROSSTARGET32], [test "x$CROSSTARGET32" != "xno"])

include/vkd3d_types.h

@@ -23,15 +23,31 @@
 extern "C" {
 #endif  /* __cplusplus */
 
+/**
+ * \file vkd3d_types.h
+ *
+ * This file contains definitions for basic types used by vkd3d libraries.
+ */
+
 #define VKD3D_FORCE_32_BIT_ENUM(name) name##_FORCE_32BIT = 0x7fffffff
 
+/**
+ * Result codes returned by some vkd3d functions. Error codes always have
+ * negative values; non-error codes never do.
+ */
 enum vkd3d_result
 {
+    /** Success. */
     VKD3D_OK = 0,
-    VKD3D_ERROR = -1, /* unspecified failure */
+    /** An unspecified failure occurred. */
+    VKD3D_ERROR = -1,
+    /** There are not enough resources available to complete the operation. */
     VKD3D_ERROR_OUT_OF_MEMORY = -2,
+    /** One or more parameters passed to a vkd3d function were invalid. */
     VKD3D_ERROR_INVALID_ARGUMENT = -3,
+    /** A shader passed to a vkd3d function was invalid. */
     VKD3D_ERROR_INVALID_SHADER = -4,
+    /** The operation is not implemented in this version of vkd3d. */
     VKD3D_ERROR_NOT_IMPLEMENTED = -5,
 
     VKD3D_FORCE_32_BIT_ENUM(VKD3D_RESULT),