www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - core.stdc in docs?

reply =?ISO-8859-1?Q?Alex_R=F8nne_Petersen?= <xtzgzorex gmail.com> writes:
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
Apr 10 2012
parent reply "Jonathan M Davis" <jmdavisProg gmx.com> writes:
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
Apr 10 2012
parent reply Jacob Carlborg <doob me.com> writes:
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
Apr 11 2012
parent Jonathan M Davis <jmdavisProg gmx.com> writes:
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
Apr 11 2012