add docs

example/list.dart

diff --git a/example/list.dart b/example/list.dart
index a4fd55a..421bba3 100644
--- a/example/list.dart
+++ b/example/list.dart
@@ -7,9 +7,15 @@
 void main(List<String> args) {
   PubCache cache = new PubCache();
 
-  print('activated applications:');
-
-  cache.getGlobalApplications().forEach((app) {
+  var apps = cache.getGlobalApplications();
+  print('${apps.length} activated applications:');
+  apps.forEach((app) {
     print('  ${app}');
   });
+
+  var packages = cache.getCachedPackages();
+  print('\n${packages.length} packages in cache:');
+  packages.forEach((pkg) {
+    print('  ${pkg}');
+  });
 }

lib/pub_cache.dart

diff --git a/lib/pub_cache.dart b/lib/pub_cache.dart
index ccbadbc..f478d6d 100644
--- a/lib/pub_cache.dart
+++ b/lib/pub_cache.dart
@@ -10,69 +10,84 @@
 import 'package:pub_semver/pub_semver.dart';
 import 'package:yaml/yaml.dart' as yaml;
 
-// TODO: get the latest version for a package?
-
-// TODO: get the latest non-dev version for a package?
-
-// TODO: Scan for git packages.
-
-/**
- * A programattic API for reflecting on Pub's cache directory.
- */
+/// A programmatic API for reflecting on Pub's cache directory.
 class PubCache {
+
+  /// Return the location of Pub's package cache.
   static Directory getSystemCacheLocation() {
-    if (Platform.environment.containsKey('PUB_CACHE')) {
-      return new Directory(Platform.environment['PUB_CACHE']);
+    Map env = Platform.environment;
+
+    if (env.containsKey('PUB_CACHE')) {
+      return new Directory(env['PUB_CACHE']);
     } else if (Platform.operatingSystem == 'windows') {
-      var appData = Platform.environment['APPDATA'];
-      return new Directory(path.join(appData, 'Pub', 'Cache'));
+      return new Directory(path.join(env['APPDATA'], 'Pub', 'Cache'));
     } else {
-      return new Directory('${Platform.environment['HOME']}/.pub-cache');
+      return new Directory('${env['HOME']}/.pub-cache');
     }
   }
 
+  // The location of the pub cache.
   final Directory location;
 
   List<Application> _applications;
   List<PackageRef> _packageRefs;
 
+  /// Create a pubcache instance. [dir] defaults to the default platform pub
+  /// cache location.
   PubCache([Directory dir]) :
       location = dir == null ? getSystemCacheLocation() : dir {
     _parse();
   }
 
-  /**
-   * Return the contents of `bin/` - the scripts for the activated applications.
-   */
-  List<File> getBinaries() {
+  /// Return the contents of `bin/` - the scripts for the activated applications.
+  List<File> getBinScripts() {
     Directory dir = _getSubDir(location, 'bin');
     return dir.existsSync() ? dir.listSync() : [];
   }
 
-  /**
-   * Return applications that have been installed via `pub global activate`.
-   */
+  /// Return applications that have been installed via `pub global activate`.
   List<Application> getGlobalApplications() => _applications;
 
-  /**
-   * Get all the packages and their versions that have been installed into the
-   * cache.
-   */
+  /// Get all the packages and their versions that have been installed into the
+  /// cache.
   List<PackageRef> getPackageRefs() => _packageRefs;
 
-  /**
-   * Return the list of package names (not versions) that are available in the
-   * cache.
-   */
+  /// Return the list of package names (not versions) that are available in the
+  /// cache.
   List<String> getCachedPackages() =>
       new Set.from(getPackageRefs().map((p) => p.name)).toList();
 
-  /**
-   * Return all available cached versions for a given package.
-   */
+  /// Return all available cached versions for a given package.
   List<PackageRef> getAllPackageVersions(String packageName) =>
       getPackageRefs().where((p) => p.name == packageName).toList();
 
+  /// Return the most recent verison of the given package contained in the
+  /// cache. This method will prefer to return only release verions. If
+  /// [includePreRelease] is true, then the very latest verision will be
+  /// returned, include pre-release versions.
+  PackageRef getLatestVersion(String packageName, {bool includePreRelease: false}) {
+    List<PackageRef> refs = getAllPackageVersions(packageName);
+
+    if (refs.isEmpty) return null;
+    if (refs.length == 1) return refs.first;
+
+    PackageRef latest = refs.first;
+
+    if (includePreRelease) {
+      for (int i = 1; i < refs.length; i++) {
+        if (refs[i].version > latest.version) latest = refs[i];
+      }
+    } else {
+      List<Version> versions = refs.map((ref) => ref.version).toList();
+      Version latestVersion = Version.primary(versions);
+      for (PackageRef ref in refs) {
+        if (ref.version == latestVersion) latest = ref;
+      }
+    }
+
+    return latest;
+  }
+
   void _parse() {
     // Read the activated applications.
     _applications = [];
@@ -94,12 +109,18 @@
           .map((dir) => new _DirectoryPackageRef('hosted', dir))
           .toList();
     }
+
+    // TODO: Scan for git packages (ignore the git/cache directory).
+    // ace-a1a140cc933e7d44d2955a6d6033308754bb9235
+
   }
 
   Directory _getSubDir(Directory dir, String name) =>
       new Directory(path.join(dir.path, name));
 }
 
+/// A Dart application; a package with an entry-point, available via `pub global
+/// activate`.
 class Application {
   final PubCache _cache;
   final Directory _dir;
@@ -108,13 +129,17 @@
 
   Application._(this._cache, this._dir);
 
+  /// The name of the defining package.
   String get name => path.basename(_dir.path);
 
+  /// The version of the application and of the defining package.
   Version get version {
     PackageRef ref = getDefiningPackageRef();
     return ref == null ? null : ref.version;
   }
 
+  /// Return the reference to the defining package. This is the package that
+  /// defines the application.
   PackageRef getDefiningPackageRef() {
     for (PackageRef ref in getPackageRefs()) {
       if (ref.name == name) return ref;
@@ -122,6 +147,8 @@
     return null;
   }
 
+  /// Return all the package references for the application. This includes the
+  /// defining package as well as the direct and transitive dependencies.
   List<PackageRef> getPackageRefs() {
     if (_packageRefs == null) _parsePubspecLock();
     return _packageRefs;
@@ -140,11 +167,18 @@
   }
 }
 
+/// A package reference, including the package name and version. This package
+/// reference can be resolved to the actual package on disk.
 abstract class PackageRef {
+  /// The type of the package reference. Valid types include `hosted` and `git`.
   String get sourceType;
+  /// The name of the package.
   String get name;
+  /// The version of the package.
   Version get version;
 
+  /// Resolve the package reference into the actual package, including the
+  /// location on disk.
   Package resolve();
 
   bool operator ==(other) {
@@ -197,6 +231,8 @@
   Package resolve() => new Package(directory, name, version);
 }
 
+/// A representation of a package, including the name, version, and location on
+/// disk.
 class Package {
   final Directory location;
   final String name;

test/pub_cache_test.dart

diff --git a/test/pub_cache_test.dart b/test/pub_cache_test.dart
index a15ba4d..064ee17 100644
--- a/test/pub_cache_test.dart
+++ b/test/pub_cache_test.dart
@@ -29,7 +29,7 @@
 
     test('getBinaries', () {
       PubCache cache = new PubCache();
-      expect(cache.getBinaries(), isNotNull);
+      expect(cache.getBinScripts(), isNotNull);
     });
 
     test('getGlobalApplications', () {
@@ -51,6 +51,16 @@
       PubCache cache = new PubCache();
       expect(cache.getAllPackageVersions('path'), isNotEmpty);
     });
+
+    test('getLatestVersion', () {
+      PubCache cache = new PubCache();
+      expect(cache.getLatestVersion('path'), isNotNull);
+    });
+
+    test('getLatestVersion.dev', () {
+      PubCache cache = new PubCache();
+      expect(cache.getLatestVersion('path', includePreRelease: true), isNotNull);
+    });
   });
 
   group('Application', () {