Scripts: add optional indentClosingBrace for function declarations

[yixun-chen]

Description

I've added a new configuration option, indentClosingBrace, to the code generator. This is a preliminary step to potentially improve the structure and readability of function declarations, especially for complex API signatures.

The Goal of This Change

1. Refpages Readability: On the Vulkan Reference Pages, long parameter lists can make the trailing ); difficult to spot. Moving it to a new line might make the signature block clearer for documentation.
2. IDE Visuals: This would allow IDE indentation guides to "close" properly, which may assist developers in scanning the code structure.

Implementation Details

The toggle is added to the generator script and is currently disabled by default to ensure no immediate changes to the current headers.

• File: scripts/genvk.py
• Line: ~588
• Default Setting:

  # scripts/genvk.py
  indentClosingBrace = False  # Set to True to enable new-line closing braces

Considerations & Impact

• Current Output: With the option set to False, the generated output remains exactly the same. This ensures no existing workflows are affected by this PR.
• Website Rendering: I am not entirely sure if this change will automatically reflect as expected on the official documentation website (Refpages), as there might be additional CSS or post-processing involved. This PR simply provides the generator-level support to test that.
• Future Flexibility: If the community finds this style preferable and it renders correctly, we can consider enabling it globally in the future by updating this single line.

---

Please let me know if this approach makes sense, or if you have any concerns about the implementation. Thanks!

[yixun-chen]

Here is a side-by-side comparison of the Vulkan Refpage and the IDE experience:
Original:

Add an indent:

And this is the side-by-side comparison for IDE(on vscode):
Original:

Add an indent:

As shown in the attached IDE screenshot, placing the closing parenthesis on a new line allows the indentation guides to properly enclose the function signature. This creates a much stronger visual 'block' and helps developers navigate large headers more efficiently.

[oddhack]

We'll discuss on the next working group teleconference - personally, I like the change. I think we would want to apply it consistently to the generated headers and to the asciidoc fragments (the docgenerator) that get included in the spec/refpages, and that's probably best accomplished by making the default True rather than littering genvk.py with a bunch of these settings.

VulkanSC might have a different opinion as they have some domain-specific constraints on their headers due to MISRA requirements. Perhaps @dgkoch or @markbellamy could comment on that.

[yixun-chen]

Thank you for the positive feedback!

I completely agree that consistency across the generated headers and Asciidoc fragments is key. Making this the default behavior to keep genvk.py clean makes a lot of sense.

Since I'm still getting familiar with the generator tools (especially the docgenerator part), I’d appreciate some guidance once the working group reaches a decision. I'm happy to update the PR to implement this more broadly as suggested.

Looking forward to the outcome of the teleconference!

[dgkoch]

It's been a bit since the VKSC WG has looked at MISRA requirements, but we don't think there are any stylistic requirements, so we don't object to it from that perspective.

That said, this seems to be purely a code-formatting stylistic option, and it seems like a slippery slope to start going down. Next we'll be arguing over spaces vs tabs or 8 space tabs vs 4 space tabs :-)

[oddhack]

There are no tabs coming out of the generator scripts, nor in the spec repository aside from the Makefiles and imported upstream files. I learned that lesson about 30 years ago and it is a hill I would die on. But I believe the sense of the teleconference was to go ahead with this once we sort it out to apply everywhere.