Hi, is it worth documenting stdc ?
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.

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.

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

On 4/26/2015 2:23 PM, Baz wrote:
> 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

Please do a PR to fix those!

On Sunday, 26 April 2015 at 21:23:24 UTC, Baz wrote:
>
> pubs.opengroup.org/onlinepubs/009695399/basedefs/_ctype.h.html
>
> while it seems to be now:
>
> pubs.opengroup.org/onlinepubs/9699919799/basedefs/ctype.h

i was wrong.
new links are for the specifications issue 7 but core.stdc API is well compliant with specifications version 6.

Actually stdc does not match version 7.

So no problems with links.

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