I know this has been discussed before, but would it really be that bad to have these in the docs? Right now, people basically head over to std.c for everything C99, and then later discover that those are to be deprecated and really just import core.stdc. I think this is rather pointless. We ought to take out std.c and add in core.stdc, IMHO.

-- 
- Alex

On Wednesday, April 11, 2012 01:28:13 Alex Rønne Petersen wrote:
> I know this has been discussed before, but would it really be that bad to have these in the docs? Right now, people basically head over to std.c for everything C99, and then later discover that those are to be deprecated and really just import core.stdc. I think this is rather pointless. We ought to take out std.c and add in core.stdc, IMHO.

Probably a good idea, but it requires putting ddoc comments on all of those functions in druntime (either empty ones or ones with links to the C docs somewhere online), which is potentially a fair bit of work. Also, in some cases, something like the StdDdoc version that Phobos uses (probably either CoreDdoc or just reuse StdDdoc) is going to have to be added to enable documentation-specific versions (without using D_Ddoc, since that runs into issue with people who try and compile their documentation and actual code at the same time - not a great practice IMO, but that's why StdDdoc exists). Also, there have been some discussions about how druntime should be split up as far as architectures and OSes go, and the documentation would be affected by that.

- Jonathan M Davis

On 2012-04-11 01:48, Jonathan M Davis wrote:

> Probably a good idea, but it requires putting ddoc comments on all of those
> functions in druntime (either empty ones or ones with links to the C docs
> somewhere online), which is potentially a fair bit of work. Also, in some
> cases, something like the StdDdoc version that Phobos uses (probably either
> CoreDdoc or just reuse StdDdoc) is going to have to be added to enable
> documentation-specific versions (without using D_Ddoc, since that runs into
> issue with people who try and compile their documentation and actual code at
> the same time - not a great practice IMO, but that's why StdDdoc exists).
> Also, there have been some discussions about how druntime should be split up
> as far as architectures and OSes go, and the documentation would be affected by
> that.
>
> - Jonathan M Davis

Perhaps a compiler switch to force outputting everything in the docs, even if they don't have any documentation comments. Then the declarations will at least show up in the documentation so people can find them.

-- 
/Jacob Carlborg

On Wednesday, April 11, 2012 10:24:40 Jacob Carlborg wrote:
> On 2012-04-11 01:48, Jonathan M Davis wrote:
> > Probably a good idea, but it requires putting ddoc comments on all of
> > those
> > functions in druntime (either empty ones or ones with links to the C docs
> > somewhere online), which is potentially a fair bit of work. Also, in some
> > cases, something like the StdDdoc version that Phobos uses (probably
> > either
> > CoreDdoc or just reuse StdDdoc) is going to have to be added to enable
> > documentation-specific versions (without using D_Ddoc, since that runs
> > into
> > issue with people who try and compile their documentation and actual code
> > at the same time - not a great practice IMO, but that's why StdDdoc
> > exists). Also, there have been some discussions about how druntime should
> > be split up as far as architectures and OSes go, and the documentation
> > would be affected by that.
> > 
> > - Jonathan M Davis
> 
> Perhaps a compiler switch to force outputting everything in the docs, even if they don't have any documentation comments. Then the declarations will at least show up in the documentation so people can find them.

It wouldn't really work in this case though, because of the OS differences. Only the stuff in the version blocks that are compiled will end up in the docs. So, if they're generated on Linux, only the linux and Posix stuff will be generated. Windows, FreeBSD, and MacOSX will be left out in the cold. The same goes if they're generated on any of the other OSes. It just changes what shows in the docs. StdDdoc (or CoreDdoc if we don't want to reuse StdDdoc in druntime) is going to need to be used liberally to document this stuff. And while that's not all that hard, it's still time consuming.

So, while your idea might be nice in theory, it doesn't really help in this particular case. Really, druntime is the prime example of where it _wouldn't_ work.

- Jonathan M Davis