Description
@avertes commented on Sat Dec 10 2016
At https://docs.microsoft.com/en-us/dotnet/core/api/system.io.file#System_IO_File_CreateText_System_String_
documentation says, that:
CreateText(String)
Creates or opens a file for writing UTF-8 encoded text.
However on my tests a file is always created (overwritten). I don't know whether the documentation should be updated to match practice or vice versa.
Repro code
using (var t = System.IO.File.CreateText("test.txt")) {
t.WriteLine("Test1");
}
using (var t = System.IO.File.CreateText("test.txt")) {
t.BaseStream.Seek(0, System.IO.SeekOrigin.End);
t.WriteLine("Test2");
}
Expected result in test.txt according to doumentation: is
Test1
Test2
However actual result (tested on Windows) is:
Test2
@mellinoe commented on Sat Dec 10 2016
The documentation seems accurate to me. Are you interpreting "opens a file for writing" as something different than what is happening?
@avertes commented on Sat Dec 10 2016
I don't think "open a file" would mean a file is overwritten.
I think create a file could mean overwrite, but if one says "create or open" then I don't see how it could be interpreted so that file is always overwritten.
I clarified my original issue description by adding the fact that result only contains "Test2"
@JonHanna commented on Sat Dec 10 2016
opens a file for writing
We can expect the file to be empty at this point, or at least appear so as far as the calling code is concerned (i.e. the actual file might not catch up with the operations done unil a sync).
Opposed to the behaviour of File.AppendText which opens a file for appending.
However on my tests a file is always created
Then the creation timestamp on the file will be changed to the current date, which does not seem to happen.
@avertes commented on Sun Dec 11 2016
Ok. I now see that I should be using AppendText for appending (duh). However it wouldn't hurt to say in the CreateText documentation that if opened file is non-empty, it will be truncated to 0. Then again, maybe I should have assumed that from the functions name.
I guess this issue can be closed if documentation brevity is preferred over completeness.
@JonHanna commented on Sun Dec 11 2016
It might still be a good idea to flesh it out a bit more. That "open for writing" includes truncating is perhaps one of those things that seem more obvious to someone familiar with the idiom than it really is, and hence the documentation seems clearer to some than it will actually read to others.
@karelz commented on Mon Dec 12 2016
Do you have suggested wording change in the docs? (ideally old text and new text)
cc: @mairaw
@avertes commented on Mon Dec 12 2016
I might not be the best person to suggest as I don't know the idioms, but think adding "empty" would make it very clear. "Creates or opens a file" => "Creates or opens an empty file"
@JonHanna commented on Mon Dec 12 2016
I think just adding:
The current contents of the file will be discarded.
After the current sentence "Creates or opens a file for writing UTF-8 encoded text." would make things clear to those who don't expect "opens for writing" to mean truncating, without being overly verbose either.
@remcoros commented on Mon Dec 12 2016
On msdn there's a good description in the Remarks section of CreateText:
https://msdn.microsoft.com/en-us/library/system.io.file.createtext(v=vs.110).aspx
Remarks
This method is equivalent to the StreamWriter(String, Boolean) constructor overload with the append parameter set to false. If the file specified by path does not exist, it is created. If the file does exist, its contents are overwritten. Additional threads are permitted to read the file while it is open.
The path parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see GetCurrentDirectory.
For a list of common I/O tasks, see Common I/O Tasks.
I don't see this (or any remarks at all) in the new documentation.
@mairaw commented on Mon Dec 12 2016
@remcoros we're still working on the solution to bring the remarks and samples over to the new site.
@avertes completeness and accurateness is always preferred over brevity.
Would it help if I manually ported the remarks to this API in particular? We still want to bring them all, but we want to do it in a more automated way. I could also change the summary to something like:
"Creates or opens a file for writing UTF-8 encoded text. If the file already exists, its contents are overwritten."
That way, people would also get that description when looking at IntelliSense in the future.
Let me know!
Also, if you have feedback on the design/layout of the new docs.microsoft.com site, provide your ideas on this UserVoice site: https://msdocs.uservoice.com/
@remcoros commented on Mon Dec 12 2016
Good to hear, the msdn docs for .net fx are very well written i.m.o., having all its content ported would be great.