[Issue 1482] New: std.file docs are insufficient

[d-bugmail at puremagic.com]

http://d.puremagic.com/issues/show_bug.cgi?id=1482

           Summary: std.file docs are insufficient
           Product: D
           Version: 2.005
          Platform: PC
        OS/Version: Linux
            Status: NEW
          Severity: normal
          Priority: P2
         Component: Phobos
        AssignedTo: bugzilla at digitalmars.com
        ReportedBy: jlquinn at us.ibm.com


The prototype for read() returns a void[].  The docs say it returns an array of
bytes.  Why does it return void[] instead of byte[] or ubyte[]?  What types is
it safe to cast the return value to?

Does read() return the complete file from a single call?

write() and append() have the same issue.  What types may be passed in safely? 
What exactly gets written out if you pass an array of dchar?

The class (and others) really need overview text at the top.  Look at the Java
API docs for inspiration.


--