---

yaml
---
r: 145949
b: refs/heads/try2
c: eaec8a7
h: refs/heads/master
i:
  145947: fbc8496
v: v3

Author: lilyball

[refs]

@@ -5,7 +5,7 @@ refs/heads/snap-stage3: 78a7676898d9f80ab540c6df5d4c9ce35bb50463
 refs/heads/try: 519addf6277dbafccbb4159db4b710c37eaa2ec5
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/ndm: f3868061cd7988080c30d6d5bf352a5a5fe2460b
-refs/heads/try2: e65d33e9ed3057a6afeaea9bf68519eb758f51ab
+refs/heads/try2: eaec8a71322a59eb284cbd5a8d502b6da321df3c
 refs/heads/dist-snap: ba4081a5a8573875fed17545846f6f6902c8ba8d
 refs/tags/release-0.2: c870d2dffb391e14efb05aa27898f1f6333a9596
 refs/tags/release-0.3: b5f0d0f648d9a6153664837026ba1be43d3e2503

branches/try2/src/libstd/path/mod.rs

@@ -8,7 +8,60 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! Cross-platform file path handling (re-write)
+/*!
+
+Cross-platform path support
+
+This module implements support for two flavors of paths. `PosixPath` represents
+a path on any unix-like system, whereas `WindowsPath` represents a path on
+Windows. This module also exposes a typedef `Path` which is equal to the
+appropriate platform-specific path variant.
+
+Both `PosixPath` and `WindowsPath` implement a trait `GenericPath`, which
+contains the set of methods that behave the same for both paths. They each also
+implement some methods that could not be expressed in `GenericPath`, yet behave
+identically for both path flavors, such as `::from_str()` or
+`.component_iter()`.
+
+The three main design goals of this module are 1) to avoid unnecessary
+allocation, 2) to behave the same regardless of which flavor of path is being
+used, and 3) to support paths that cannot be represented in UTF-8 (as Linux has
+no restriction on paths beyond disallowing NUL).
+
+## Usage
+
+Usage of this module is fairly straightforward. Unless writing platform-specific
+code, `Path` should be used to refer to the platform-native path, and methods
+used should be restricted to those defined in `GenericPath`, and those methods
+that are declared identically on both `PosixPath` and `WindowsPath`.
+
+Creation of a path is typically done with either `Path::from_str(some_str)` or
+`Path::from_vec(some_vec)`. This path can be modified with `.push()` and
+`.pop()` (and other setters). The resulting Path can either be passed to another
+API that expects a path, or can be turned into a &[u8] with `.as_vec()` or a
+Option<&str> with `.as_str()`. Similarly, attributes of the path can be queried
+with methods such as `.filename()`. There are also methods that return a new
+path instead of modifying the receiver, such as `.join()` or `.dir_path()`.
+
+When rendering a path to some form of display, there is a method `.display()`
+which is compatible with the `format!()` parameter `{}`. This will render the
+path as a string, replacing all non-utf8 sequences with the Replacement
+Character (U+FFFD). As such it is not suitable for passing to any API that
+actually operates on the path; it is only intended for display.
+
+## Example
+
+```rust
+let mut path = Path::from_str("/tmp/path");
+debug2!("path: {}", path.display());
+path.set_filename_str("foo");
+path.push_str("bar");
+debug2!("new path: {}", path.display());
+let b = std::os::path_exists(&path);
+debug2!("path exists: {}", b);
+```
+
+*/
 
 use container::Container;
 use c_str::CString;