search

vulkan-go / vulkan

Vulkan API bindings for Go programming language
MIT License
744 stars 56 forks source link

documentation as links not ideal #18

Open splace opened 6 years ago

splace commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

src="/assets/static/detect-f5c850050acb63fb62a5bdab0fae8503.min.js">

> 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 commented 6 years ago

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.