Rework the readme

[sharadhr]

No description provided.

[asuessenbach]

Is there a reason you want to rework the readme?

[sharadhr]

Hi @asuessenbach! I've been meaning to do this for a while, actually. I have a list of things that I found a little less than ideal with the current readme:

• Be clear on what this repository is actually for (development of the Vulkan-Hpp generator); the actual generated headers can be downloaded from Vulkan-Headers.
• More instructions on installation/usage from the Vulkan SDK, vcpkg, and Conan.
• Rearranging some of the information to flow a bit better; e.g. start with basic Info structs, then move on to specific Vulkan types like Device, Image, etc
  • Some of the information is a bit scattershot; e.g. there are two sections for RAII best practices; these could be combined.
  • Subsume the RAII programming guide into the readme, or split the readme up altogether.
  • Also group together the language-side facilities that Vulkan-Hpp uses, e.g. [[nodiscard]], std::expected, std::optional, etc
• Remove/edit deprecated information, especially pertaining to vulkan.cppm
• Miscellaneous grammar, capitalisation, and formatting (e.g. as demonstrated, making all the configuration options demarcated ``in backticks`` makes it easy to avoid the \_stuff in the ToC.
  • Adhere to some Common Markdown best practices, e.g. spaces around lists, - instead of *, etc.
  • Also, the HTML hyperlinks are no longer necessary; as far as I understand, the Common Markdown specification provides a means to automatically generate a table of contents.

If you're OK with this, I can proceed with making these changes, naturally subject to your review at the end. I hope to improve the documentation at the end of this exercise.

[asuessenbach]

You're more than welcome to rework the readme!
I'm pretty sure, any change will be an improvement.

[sharadhr]

@asuessenbach, this is still in progress (and hence in draft mode), but do feel free to have a look at the branch to see the direction I'm going in. Hopefully intend to complete this by the end of the year.

[M2-TE]

How about adding CMake's FetchContent to the "Installation and Usage" section?
Something akin to

include(FetchContent)
FetchContent_Declare(vulkan-hpp
    GIT_REPOSITORY "https://github.com/KhronosGroup/Vulkan-Hpp.git"
    GIT_TAG "v1.4.336" # release tag, commit hash or branch name
    GIT_SHALLOW ON)
FetchContent_MakeAvailable(vulkan-hpp)

[M2-TE]

For the "Build Instructions", it is likely best to separate header generation and sample/test building. At the very least, the build section should state that building is purely for those tasks and that headers can be used by just including them.

For merely using the headers (because e.g. they haven't landed in Vulkan-Headers yet), quickly showing how to link against Vulkan::Hpp in CMake would be sufficient for those users. Or showing minimal include_directories(...) usage.

[sharadhr]

Both good points @M2-TE. I am focusing mostly on Usage for now (since that is where I see the biggest shortfall in documentation), but I will add these in to Building when I can.