On Friday, January 27, 2012 10:39:41 Sean Kelly wrote: > System headers are absolutely required for Druntime to build. This is one > of the reasons core.stdc and core.sys exist. Documentation isn't generated > because these are interfaces to external APIs, so the documentation for > those APIs should be referenced when coding to them. We could add an empty > doc comment to every declaration so something was generated in the Druntime > docs, but I don't know why anyone would ever actually refer to them.
The value in having empty ddoc comments is so that if you need to use any of the functions in them for some reason (which _does_ happen upon occasion), then you know what module has what without having to go find the source code and look through it. So, ideally, all of the declarations in druntime for the C APIs should at least have empty ddoc so that they're documented. I completely agree that it's best not to try and duplicate the full documentation for them - that's best left to the C docs - but documenting what's there is still valuable, and we should probably do that at some point. - Jonathan M Davis
