---

yaml
---
r: 83331
b: refs/heads/try
c: a5cf9fd
h: refs/heads/master
i:
  83329: fb67f32
  83327: a07e49f
v: v3

Author: bytbox

[refs]

@@ -2,7 +2,7 @@
 refs/heads/master: 0e4d1fc8cae42e15e00f71d9f439b01bb25a86ae
 refs/heads/snap-stage1: e33de59e47c5076a89eadeb38f4934f58a3618a6
 refs/heads/snap-stage3: 6c08cc2db4f98e9f07ae7d50338396c4123c2f0a
-refs/heads/try: 33e913d9cfa2519993740bbbea592697f3aa950d
+refs/heads/try: a5cf9fdb61432ea0182dc250305332f3a2d6f214
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/ndm: f3868061cd7988080c30d6d5bf352a5a5fe2460b
 refs/heads/try2: 147ecfdd8221e4a4d4e090486829a06da1e0ca3c

branches/try/src/libextra/semver.rs

@@ -8,10 +8,25 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! Semver parsing and logic
-
-#[allow(missing_doc)];
-
+//! Semantic version parsing and comparison.
+//!
+//! Semantic versioning (see http://semver.org/) is a set of rules for
+//! assigning version numbers intended to convey meaning about what has
+//! changed, and how much. A version number has five parts:
+//!
+//!  * Major number, updated for incompatible API changes
+//!  * Minor number, updated for backwards-compatible API additions
+//!  * Patch number, updated for backwards-compatible bugfixes
+//!  * Pre-release information (optional), preceded by a hyphen (`-`)
+//!  * Build metadata (optional), preceded by a plus sign (`+`)
+//!
+//! The three mandatory components are required to be decimal numbers. The
+//! pre-release information and build metadata are required to be a
+//! period-separated list of identifiers containing only alphanumeric
+//! characters and hyphens.
+//!
+//! An example version number with all five components is
+//! `0.8.1-rc.3.0+20130922.linux`.
 
 use std::char;
 use std::cmp;
@@ -20,6 +35,8 @@ use std::io;
 use std::option::{Option, Some, None};
 use std::to_str::ToStr;
 
+/// An identifier in the pre-release or build metadata. If the identifier can
+/// be parsed as a decimal value, it will be represented with `Numeric`.
 #[deriving(Clone, Eq)]
 pub enum Identifier {
     Numeric(uint),
@@ -49,12 +66,20 @@ impl ToStr for Identifier {
 }
 
 
+/// Represents a version number conforming to the semantic versioning scheme.
 #[deriving(Clone, Eq)]
 pub struct Version {
+    /// The major version, to be incremented on incompatible changes.
     major: uint,
+    /// The minor version, to be incremented when functionality is added in a
+    /// backwards-compatible manner.
     minor: uint,
+    /// The patch version, to be incremented when backwards-compatible bug
+    /// fixes are made.
     patch: uint,
+    /// The pre-release version identifier, if one exists.
     pre: ~[Identifier],
+    /// The build metadata, ignored when determining version precedence.
     build: ~[Identifier],
 }
 
@@ -202,6 +227,7 @@ fn parse_reader(rdr: @io::Reader) -> Version {
 }
 
 
+/// Parse a string into a semver object.
 pub fn parse(s: &str) -> Option<Version> {
     if !s.is_ascii() {
         return None;