www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.learn - No documentation for core.sys?

reply Shriramana Sharma <samjnaa_dont_spam_me gmail.com> writes:
In my recent search for D's equivalent of isatty, I found out that there is 
a core.sys.posix module only by rgrepping under /usr/include/dmd. Why isn't 
there a documentation page http://dlang.org/phobos/core_sys.html whereas 
lots of other core.* modules are documented?

--
Dec 16 2015
next sibling parent reply Jakob Ovrum <jakobovrum gmail.com> writes:
On Thursday, 17 December 2015 at 03:40:02 UTC, Shriramana Sharma 
wrote:

 In my recent search for D's equivalent of isatty, I found out 
 that there is a core.sys.posix module only by rgrepping under 
 /usr/include/dmd. Why isn't there a documentation page 
 http://dlang.org/phobos/core_sys.html whereas lots of other 
 core.* modules are documented?


core.sys contains packages with system-specific D interface files 
(ports of header files). As with core.stdc, refer to the 
documentation for the equivalent C header.
Dec 16 2015
next sibling parent reply Shriramana Sharma <samjnaa_dont_spam_me gmail.com> writes:
Jakob Ovrum wrote:


 As with core.stdc, refer to the
 documentation for the equivalent C header.


I only know of even core.stdc's existence since I've been poking into the 
Phobos sources. At least the Phobos documentation should mention that such 
modules exist.

I note that in the proposed library documentation, core.stdc is mentioned: 
https://dlang.org/library/index.html, but core.sys.posix is not...

[sigh] This is why D's API version is still 0, as in 2.0.69.2 (at least my 
interpretation of the weird zero-prefixed numbering being used).

--
Dec 16 2015
parent Jakob Ovrum <jakobovrum gmail.com> writes:
On Thursday, 17 December 2015 at 04:23:30 UTC, Shriramana Sharma 
wrote:

 Jakob Ovrum wrote:


 As with core.stdc, refer to the
 documentation for the equivalent C header.


 I only know of even core.stdc's existence since I've been 
 poking into the Phobos sources. At least the Phobos 
 documentation should mention that such modules exist.


Maybe. The thing is, the bindings in core.sys have been built on 
an as-needed (by druntime or Phobos) basis, so some of them are 
incomplete and some headers are probably missing. That said, I'm 
not very familiar with it, so maybe the current status is 
different. I know for one thing that core.sys.windows recently 
had a major overhaul.


 [sigh] This is why D's API version is still 0, as in 2.0.69.2 
 (at least my interpretation of the weird zero-prefixed 
 numbering being used).


Uh, hyperbole much?

https://github.com/D-Programming-Language/druntime/pull/1402
Dec 16 2015
prev sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2015-12-17 04:47, Jakob Ovrum wrote:


 core.sys contains packages with system-specific D interface files (ports
 of header files). As with core.stdc, refer to the documentation for the
 equivalent C header.


core.stdc is documented, in the sense that empty doc comments have been 
added to all symbols to make them show up in the docs [1]. I think the 
same should be done for core.sys as well. Then at least you know it 
exists and then can look up the documentation for the C header file for 
more information.

[1] I think it was Steven Schveighoffer that did that enormous work.

-- 
/Jacob Carlborg
Dec 16 2015
parent Steven Schveighoffer <schveiguy yahoo.com> writes:
On 12/17/15 2:30 AM, Jacob Carlborg wrote:

 On 2015-12-17 04:47, Jakob Ovrum wrote:


 core.sys contains packages with system-specific D interface files (ports
 of header files). As with core.stdc, refer to the documentation for the
 equivalent C header.


 core.stdc is documented, in the sense that empty doc comments have been
 added to all symbols to make them show up in the docs [1]. I think the
 same should be done for core.sys as well. Then at least you know it
 exists and then can look up the documentation for the C header file for
 more information.

 [1] I think it was Steven Schveighoffer that did that enormous work.


s/enormous/tedious

As far as sys, the mapping to c headers may not be as straightforward as 
core.stdc. I agree that we should tag those for documenting, but it may 
not be as easy to refer to the c documentation.

-Steve
Dec 17 2015
prev sibling parent Adam D. Ruppe <destructionator gmail.com> writes:
On Thursday, 17 December 2015 at 03:40:02 UTC, Shriramana Sharma 
wrote:

 Why isn't there a documentation page 
 http://dlang.org/phobos/core_sys.html whereas lots of other 
 core.* modules are documented?


Because the D build process is f***ed up and the website build 
process is yet another layer of crap on top of it.

I'm sorry to be so harsh, but that's the simple truth of the 
matter. I recently added a new binding module in there and it 
took me, plus the reviewers, like four iterations just to get it 
included in the druntime build correctly (and it is just 
bindings! it doesn't even do anything) and the website build 
duplicates those lists AGAIN.


BTW, I run a D documentation search engine that digs deeper than 
the main page:

http://dpldocs.info/isatty

Stick a function name in there and see what it gives you. For 
isatty, it gives:

core.sys.posix.unistd.isatty
D code»D Builtins»core.sys.posix.unistd


telling you that it is there, though no extra docs are written. 
Then you can try finding it on the real site or just importing it.

It is useful to find the module for functions as tehy move too:

http://dpldocs.info/walkLength

walkLength [4]D code»D Builtins»std.range.primitives

This is a best-effort implementation of $(D length) for any kind 
of range.



Not perfect, but helps to find things. It also has indexed my 
modules:

http://dpldocs.info/simpledisplay.SimpleWindow



The docs aren't really readable there but the indexing helps find 
where to look.
Dec 17 2015