documentation as links not ideal

[splace]

example

// Flags type as declared in https://www.khronos.org/registry/vulkan/specs/1.0/man/html/VkFlags.html
type Flags uint32

seems to me a couple of issues with providing documentation as links to documentation.

1. in the case above the link target has changed, or rather is redirected, in the case above its to https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/VkFlags.html which i guess is fine since i would say its very likely still valid for version 1.0., but its surprising.

2. when browsing, trying to grok the rather large API, having everything a link to follow is so time consuming as to really render the documentation, for this use case, useless.

so, a feature request, any chance the documentaton (summary) be copied and just inlined in the code?

[xlab]

Hi, the links are generated automatically without any analysis, the generator just puts a prefix + the name of an object. Some links are simply broken. I acknowledge the problem, but there is no a quck way to fix that, I can't edit the codebase since it's autogenerated from C sources..

I will think about better approach, but the problem remains open.

[splace]

Thanks,

i submitted the issue hoping the auto-generator had this ability.

i originally thought about doing this with some go code myself, could go back to that, since now i get its the C sources that have the references.

i'll look in to how i might textify the html, maybe the spec pages have some nice style/content separation.

[splace]

after some thought, and checking...

khronos only do the spec., no software, their product is the spec., and its open source, but the documentation of the spec. is copyrighted, it does allow copying but not re-distribution.

so the descriptions shouldn't be included in this wrapper, as they weren't, and thats probably why the C has links.

however;

if you had some code that could download, parse out the info. and insert it in the code, and then have it run during installation, then that would be ok. but thats a big ask, but it would possibly be of more general use, if/when this happens with other wrappers.

[hankpin]

src="/assets/static/detect-f5c850050acb63fb62a5bdab0fae8503.min.js"></script> <script src="/assets/static/app-e7a00f5a7d3bfd87c9f9225bd04e67b9.min.js"></script> </body> </html>

…

On Jun 2, 2018, at 12:10 PM, simon place ***@***.***> wrote: after some thought, and checking... khronos only do the spec., no software, their product is the spec., and its open source, but the documentation of the spec. is copyrighted, it does allow copying but not re-distribution. so the descriptions shouldn't be included in this wrapper, as they weren't, and thats probably why the C has links. however; if you had some code that could download, parse out the info. and insert it in the code, and then have it run during installation, then that would be ok. but thats a big ask, but it would possibly be of more general use, if/when this happens with other wrappers. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, or mute the thread.

[splace]

well confusingly and inconsistently AFAIKT

the main site, and full spec. page, say no redistribution, but the individual function webpages, claiming to have been extracted from the full spec., are "Attribution 4.0 International" which allows distribution and modification, so they CAN just be inserted, i guess. i'll take a look.