On 4/26/15 5:23 PM, Baz wrote:
On Sunday, 26 April 2015 at 20:45:32 UTC, Walter Bright wrote:
On 4/26/2015 11:38 AM, Baz wrote:
Hi, is it worth documenting stdc ?
No. In general, D should not be re-documenting APIs where the
documentation exists elsewhere, because:
1. have to rewrite it because of copyright
2. such rewrites introduce errors and ambiguities
3. documentation always gets out of date
4. a user would be foolish to use re-documentation rather than the
official documentation
5. our time is much better expended on more productive things.
I'm about to copy all the docs from offical sources, e.g
http://www.cplusplus.com/reference/cctype/.
There's been a post from W.B a few weeks ago about undocumented sources.
I don't remember if it included stdc.
It doesn't include API interfaces.
Thanks for asking before doing the work. I'd sure hate for you to
expend a lot of effort on this only to have it rejected. We can't
afford to waste effort like that.
Well, i should have waited because i've started and now i realize it
wouldn't be human to do that in one shot anyway.
By the way, the stdc ddoc headers include some invalid addresses, e.g:
pubs.opengroup.org/onlinepubs/009695399/basedefs/_ctype.h.html
while it seems to be now:
pubs.opengroup.org/onlinepubs/9699919799/basedefs/ctype.h
I added all those a while back. The idea is to have *some* documentation
for what we have in core.stdc (previously, no ddocs were generated).
When I put all those links up, I wasn't sure if those would change, and
probably, I didn't use the latest one (whatever google came up with!).
I'm wondering if a good PR would be to change the links so instead of
the full URL, you pass in just the last part (i.e. the _ctype.h.html),
and put the base in the macro. This way, we can easily update the whole
set of links.
And at that time, you can upgrade to the latest version! I'm fairly
certain the links would continue to follow the same structure (I found
only one link on google, and then generated the rest by substituting the
header name at the end).
-Steve
