API documentation: C runtime behavior of std.ascii.newline

[dlangBugzillaToGithub]

andre reported this on 2016-09-28T17:20:22Z

Transfered from https://issues.dlang.org/show_bug.cgi?id=16561

CC List

• greeenify

Description

For users without C knowledge there is some magic if std.stdio.File was opened with "w". I just learned the C runtime translates 
 to \r
 in the background.

I was using std.ascii.newline because I tried to write OS independent code, but I wondered why the file endings where somehow broken. Please see 
https://forum.dlang.org/post/smslryopqywdwtzicxnp@forum.dlang.org

The API reference https://dlang.org/phobos/std_stdio.html#.File
lacks information about this behavior. There is only a link to a C documentiation (http://cplusplus.com/reference/clibrary/cstdio/fopen.html) which also do not explain this behavior.

The only hint is: Use std.ascii.newline for portability (unless the file was opened in text mode)

The API documentation should be enhanced to avoid other D users will fell into this trap.