---

yaml
---
r: 83133
b: refs/heads/auto
c: eaec8a7
h: refs/heads/master
i:
  83131: 3bb617e
v: v3

Author: lilyball

[refs]

@@ -13,7 +13,7 @@ refs/heads/try3: 9387340aab40a73e8424c48fd42f0c521a4875c0
 refs/tags/release-0.3.1: 495bae036dfe5ec6ceafd3312b4dca48741e845b
 refs/tags/release-0.4: e828ea2080499553b97dfe33b3f4d472b4562ad7
 refs/tags/release-0.5: 7e3bcfbf21278251ee936ad53e92e9b719702d73
-refs/heads/auto: e65d33e9ed3057a6afeaea9bf68519eb758f51ab
+refs/heads/auto: eaec8a71322a59eb284cbd5a8d502b6da321df3c
 refs/heads/servo: af82457af293e2a842ba6b7759b70288da276167
 refs/tags/release-0.6: b4ebcfa1812664df5e142f0134a5faea3918544c
 refs/tags/0.1: b19db808c2793fe2976759b85a355c3ad8c8b336

branches/auto/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;