diff --git a/src/vs/base/common/paging.ts b/src/vs/base/common/paging.ts
index ee6d1b28ddc56cf662c0d57de216b16c2146850b..5706b6c3c8575f47a1a341f616b928f0eeef5e5a 100644
--- a/src/vs/base/common/paging.ts
+++ b/src/vs/base/common/paging.ts
@@ -8,6 +8,9 @@
 import { TPromise } from 'vs/base/common/winjs.base';
 import { ArraySet } from 'vs/base/common/set';
 
+/**
+ * A Pager is a stateless abstraction over a paged collection.
+ */
 export interface IPager<T> {
 	firstPage: T[];
 	total: number;
@@ -22,7 +25,17 @@ interface IPage<T> {
 	elements: T[];
 }
 
-export class PagedModel<T> {
+/**
+ * A PagedModel is a stateful model over an abstracted paged collection.
+ */
+export interface IPagedModel<T> {
+	length: number;
+	isResolved(index: number): boolean;
+	get(index: number): T;
+	resolve(index: number): TPromise<T>;
+}
+
+export class PagedModel<T> implements IPagedModel<T> {
 
 	private pages: IPage<T>[] = [];
 
@@ -92,6 +105,10 @@ export class PagedModel<T> {
 	}
 }
 
+/**
+ * Similar to array.map, `mapPager` lets you map the elements of an
+ * abstract paged collection to another type.
+ */
 export function mapPager<T,R>(pager: IPager<T>, fn: (t: T) => R): IPager<R> {
 	return {
 		firstPage: pager.firstPage.map(fn),