[PATCH vkd3d 1/5] include: Add basic documentation for vkd3d_types.h.

[Henri Verbeet]

On Thu, 27 Aug 2020 at 07:46, Zebediah Figura <z.figura12 at gmail.com> wrote:
> diff --git a/Doxyfile.in b/Doxyfile.in
> new file mode 100644
> index 00000000..f5f88dbf
> --- /dev/null
> +++ b/Doxyfile.in
> @@ -0,0 +1,17 @@
> +# Doxyfile 1.8.18
> +
> +DOXYFILE_ENCODING      = UTF-8
> +PROJECT_NAME           = @PACKAGE_NAME@
> +PROJECT_NUMBER         = @PACKAGE_VERSION@
> +PROJECT_BRIEF          = "D3D12 to Vulkan translation library"
For what it's worth, in the pkg-config description we use "The vkd3d
3D Graphics Library".

> +OUTPUT_DIRECTORY       = @srcdir@/doc
I'm by no means a Doxygen expert, but is that correct? I would expect
the output to go to @builddir at .

> +DX_INIT_DOXYGEN(vkd3d, [Doxyfile], [doc])
It often happens to work without, but I think it's good practice to
quote literal macro arguments.

> +/** Result codes returned by some vkd3d functions. */
>  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,
Error codes have negative values; non-error codes never do.