www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - [hackathlon] stdc ddoc needed ?

reply "Baz" <bb.temp gmx.com> writes:
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.
Apr 26 2015
parent reply Walter Bright <newshound2 digitalmars.com> writes:
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.
Apr 26 2015
parent reply "Baz" <bb.temp gmx.com> writes:
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
Apr 26 2015
next sibling parent Walter Bright <newshound2 digitalmars.com> writes:
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!
Apr 26 2015
prev sibling next sibling parent "Baz" <bb.temp gmx.com> writes:
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.
Apr 26 2015
prev sibling parent Steven Schveighoffer <schveiguy yahoo.com> writes:
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
Apr 27 2015