Add docs for extra::semver

Author: bytbox

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;