[phobos] next release (module useability)

[Lars Tandle Kyllingstad]

On Tue, 2010-09-14 at 18:21 -0700, Walter Bright wrote:
> stdio is for buffered file I/O, file is for encapsulated file ops.

...and std.path is just string manipulation.  I have to say, I really
like the way these three modules are separated now.

Before, I used to make mistakes such as importing std.file to use File,
or importing std.path to use getcwd().   But then, one day, I understood
why the modules are organised the way they are, and I don't think I've
ever made such mistakes again.

Perhaps the documentation of the modules could be improved to help users
understand this right away?  Suggestions:

std.file:
        This module is for encapsulated file operations, such as
        copying, deleting, and renaming files, as well as directory
        manipulation.  It also contains functions that read and write
        entire files in one operation.
        
        See_also:
        std.stdio, for general I/O-related functionality.
        std.path, for path-related string operations.


std.stdio:
        bla bla bla...
        
        See_also:
        std.file, which contains methods to read and write entire files
        in one operation.


std.path:
        bla bla bla...
        
        See_also:
        std.file, for functions that perform actual filesystem
        operations (copying, renaming, deleting, etc.).

-Lars