Accompanying destruction functions are not easily accessible in the spec

[avoroshilov]

Hello!

In online registry pages like this one: https://www.khronos.org/registry/vulkan/specs/1.0/man/html/vkCreateImage.html
or in the spec pages, the accompanying destruction functions are not referenced near to the creation functions. They could only be accessed if to go to the upper level (through the See also section):
https://www.khronos.org/registry/vulkan/specs/1.0/man/html/VkImage.html
and then reference to vkDestroyImage will be somewhere in the middle of See also block, not immediately obvious too.

So the suggestion would be to:

1. add accompanying destruction functions to the See also section of the creation function and vice versa for the destruction functions (i.e. vkCreateImage will reference vkDestroyImage, and vkDestroyImage will reference vkCreateImage);
2. put the lifetime management functions at the beginning of the See also block of the object itself (e. g. VkImage See also block will have vkCreateImage as a first reference and vkDestroyImage as a second)
3. maybe even have a separate subsection in the See also section, specifically for the lifetime management functions where applicable

Thank you!

[oddhack]

Thanks, that's a good suggestion. Parts 1 and 2 can be done by adding the proper commands in the xrefs= attribute of the open block surrounding each relevant command, which is easy but tedious. It would require some changes to the ref page extraction scripts to do part 3. I'll take a look at this as time allows, or you can propose a PR to the repository making these changes.

[avoroshilov]

I forked the Vulkan-Docs repository today and played around with it, but initially as I didn't know that references could be implicit, I failed to follow your instructions at first.
Instead, I went the other way, and modified doc\specs\vulkan\genRef.py, function seeAlsoList (see this commit for the exact code), which allowed to create automatic matching of the functions.
There are 2 main reasons why I don't like this approach:

1. the pairs and priority prefixes are defined inside the script, while script should be agnostic to the actual vulkan values;
2. there are functions that do not have strictly matching pairs, like vkCreateMirSurfaceKHR which will have matching vkDestroySurfaceKHR; the pair search that I implemented has a verification via presence in mapDict.keys, so "invalid" functions should never get to the See also list, i.e. vkDestroyMirSurfaceKHR will not be a thing listed/displayed;

Then I tracked down the explicitRefs in the seeAlsoList and found which xrefs you initially meant (in the doc\specs\vulkan\chapters\ folder). However, this will not allow for the item 2 from the original list to be implemented, as the seeAlsoList does sorting of the references.

This made me think that the two approaches could be combined, with the following modifications of my initial approach:

1. create text file(s) in the doc\specs\vulkan\chapters\ or doc\specs\vulkan\config\ folder, which will state the pairs correspondence and priority prefixes list;
2. functions that do not have strictly matching pairs, could be augmented with xrefs that you initially suggested, e.g. vkCreateMirSurfaceKHR will have xrefs='vkDestroySurfaceKHR' defined in VK_KHR_mir_surface\platformCreateSurface_mir.txt; this will also work with the priority prefixes sorting, i.e. vkDestroySurfaceKHR will appear first in the See also list;

This would allow to save manual labor on adding explicit xrefs to each and every member of vkCreate*/vkDestroy* and vkAllocate*/vkFree*, while still be flexible for further modifications.