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?

-- 
Shriramana Sharma, Penguin #395953
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). -- Shriramana Sharma, Penguin #395953
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