diff --git a/src/Umbraco.Web/Routing/DefaultRoutesCache.cs b/src/Umbraco.Web/Routing/DefaultRoutesCache.cs
index b4daefaea2..55a2c08e75 100644
--- a/src/Umbraco.Web/Routing/DefaultRoutesCache.cs
+++ b/src/Umbraco.Web/Routing/DefaultRoutesCache.cs
@@ -6,7 +6,7 @@ using Umbraco.Core;
 namespace Umbraco.Web.Routing
 {
 	/// <summary>
-	/// The default implementation of IRoutesCache
+	/// Provides a default implementation of <see cref="IRoutesCache"/>.
 	/// </summary>
 	internal class DefaultRoutesCache : IRoutesCache
 	{
@@ -14,23 +14,31 @@ namespace Umbraco.Web.Routing
 		private Dictionary<int, string> _routes;
         private Dictionary<string, int> _nodeIds;
 
+		/// <summary>
+		/// Initializes a new instance of the <see cref="DefaultRoutesCache"/> class.
+		/// </summary>
         public DefaultRoutesCache()
         {
             Clear();
 
-            // here we should register handlers to clear the cache when content changes
-            // at the moment this is done by library, which clears everything when content changed
-            //
-            // but really, we should do some partial refreshes!
-            // otherwise, we could even cache 404 errors...
-			//
-			// these are the two events used by library in legacy code...
-			// is it enough?
+			//FIXME:
 			//
+            // here we must register handlers to clear the cache when content changes
+			// this was done by presentation.library, which cleared everything when content changed
+            // but really, we should do some partial refreshes
+
+			// these are the two events that were used by presentation.library
+			// are they enough?
+
 			global::umbraco.content.AfterRefreshContent += (sender, e) => Clear();
 			global::umbraco.content.AfterUpdateDocumentCache += (sender, e) => Clear();
         }
 
+		/// <summary>
+		/// Stores a route for a node.
+		/// </summary>
+		/// <param name="nodeId">The node identified.</param>
+		/// <param name="route">The route.</param>
         public void Store(int nodeId, string route)
         {
             using (new WriteLock(_lock))
@@ -40,6 +48,11 @@ namespace Umbraco.Web.Routing
             }
         }
 
+		/// <summary>
+		/// Gets a route for a node.
+		/// </summary>
+		/// <param name="nodeId">The node identifier.</param>
+		/// <returns>The route for the node, else null.</returns>
         public string GetRoute(int nodeId)
         {
             lock (new ReadLock(_lock))
@@ -48,6 +61,11 @@ namespace Umbraco.Web.Routing
             }
         }
 
+		/// <summary>
+		/// Gets a node for a route.
+		/// </summary>
+		/// <param name="route">The route.</param>
+		/// <returns>The node identified for the route, else zero.</returns>
         public int GetNodeId(string route)
         {
             using (new ReadLock(_lock))
@@ -56,6 +74,10 @@ namespace Umbraco.Web.Routing
             }
         }
 
+		/// <summary>
+		/// Clears the route for a node.
+		/// </summary>
+		/// <param name="nodeId">The node identifier.</param>
         public void ClearNode(int nodeId)
         {
             using (var lck = new UpgradeableReadLock(_lock))
@@ -69,6 +91,9 @@ namespace Umbraco.Web.Routing
             }
         }
 
+		/// <summary>
+		/// Clears all routes.
+		/// </summary>
         public void Clear()
         {
             using (new WriteLock(_lock))
diff --git a/src/Umbraco.Web/Routing/DocumentRequest.cs b/src/Umbraco.Web/Routing/DocumentRequest.cs
index d9b450b2a5..bc25fc0fbc 100644
--- a/src/Umbraco.Web/Routing/DocumentRequest.cs
+++ b/src/Umbraco.Web/Routing/DocumentRequest.cs
@@ -155,7 +155,7 @@ namespace Umbraco.Web.Routing
             Trace.TraceInformation("{0}Uri=\"{1}\"", tracePrefix, this.Uri);
 
             // try to find a domain matching the current request
-			var domainAndUri = Domains.ApplicableDomains(Domain.GetDomains(), RoutingContext.UmbracoContext.UmbracoUrl, false);
+			var domainAndUri = Domains.DomainMatch(Domain.GetDomains(), RoutingContext.UmbracoContext.UmbracoUrl, false);
 
             // handle domain
 			if (domainAndUri != null)
diff --git a/src/Umbraco.Web/Routing/Domains.cs b/src/Umbraco.Web/Routing/Domains.cs
index 01b5def78a..72454c3718 100644
--- a/src/Umbraco.Web/Routing/Domains.cs
+++ b/src/Umbraco.Web/Routing/Domains.cs
@@ -8,20 +8,48 @@ using umbraco.cms.businesslogic.web;
 
 namespace Umbraco.Web.Routing
 {
+	/// <summary>
+	/// Provides utilities to handle domains.
+	/// </summary>
 	public class Domains
 	{
+		/// <summary>
+		/// Represents an Umbraco domain and its normalized uri.
+		/// </summary>
+		/// <remarks>
+		/// <para>In Umbraco it is valid to create domains with name such as <c>example.com</c>, <c>https://www.example.com</c>, <c>example.com/foo/</c>.</para>
+		/// <para>The normalized uri of a domain begins with a scheme and ends with no slash, eg <c>http://example.com/</c>, <c>https://www.example.com/</c>, <c>http://example.com/foo/</c>.</para>
+		/// </remarks>
 		public class DomainAndUri
 		{
+			/// <summary>
+			/// The Umbraco domain.
+			/// </summary>
 			public Domain Domain;
+
+			/// <summary>
+			/// The normalized uri of the domain.
+			/// </summary>
 			public Uri Uri;
 
+			/// <summary>
+			/// Gets a string that represents the <see cref="DomainAndUri"/> instance.
+			/// </summary>
+			/// <returns>A string that represents the current <see cref="DomainAndUri"/> instance.</returns>
 			public override string ToString()
 			{
 				return string.Format("{{ \"{0}\", \"{1}\" }}", Domain.Name, Uri);
 			}
 		}
 
-		public static DomainAndUri ApplicableDomains(IEnumerable<Domain> domains, Uri current, bool defaultToFirst)
+		/// <summary>
+		/// Finds the domain that best matches the current uri, into an enumeration of domains.
+		/// </summary>
+		/// <param name="domains">The enumeration of Umbraco domains.</param>
+		/// <param name="current">The uri of the current request, or null.</param>
+		/// <param name="defaultToFirst">A value indicating whether to return the first domain of the list when no domain matches.</param>
+		/// <returns>The domain and its normalized uri, that best matches the current uri, else the first domain (if <c>defaultToFirst</c> is <c>true</c>), else null.</returns>
+		public static DomainAndUri DomainMatch(IEnumerable<Domain> domains, Uri current, bool defaultToFirst)
 		{
 			if (!domains.Any())
 				return null;
@@ -57,6 +85,29 @@ namespace Umbraco.Web.Routing
 			return domainAndUri;
 		}
 
+		/// <summary>
+		/// Gets an enumeration of <see cref="DomainAndUri"/> matching an enumeration of Umbraco domains.
+		/// </summary>
+		/// <param name="domains">The enumeration of Umbraco domains.</param>
+		/// <param name="current">The uri of the current request, or null.</param>
+		/// <returns>The enumeration of <see cref="DomainAndUri"/> matching the enumeration of Umbraco domains.</returns>
+		public static IEnumerable<DomainAndUri> DomainMatches(IEnumerable<Domain> domains, Uri current)
+		{
+			var scheme = current == null ? Uri.UriSchemeHttp : current.Scheme;
+			var domainsAndUris = domains
+				.Select(d => new { Domain = d, UriString = UriUtility.TrimPathEndSlash(UriUtility.StartWithScheme(d.Name, scheme)) })
+				.OrderByDescending(t => t.UriString)
+				.Select(t => new DomainAndUri { Domain = t.Domain, Uri = new Uri(t.UriString) });
+			return domainsAndUris;
+		}
+
+		/// <summary>
+		/// Returns the part of a path relative to the uri of a domain.
+		/// </summary>
+		/// <param name="domainUri">The normalized uri of the domain.</param>
+		/// <param name="path">The full path of the uri.</param>
+		/// <returns>The path part relative to the uri of the domain.</returns>
+		/// <remarks>Eg the relative part of <c>/foo/bar/nil</c> to domain <c>example.com/foo</c> is <c>/bar/nil</c>.</remarks>
 		public static string PathRelativeToDomain(Uri domainUri, string path)
 		{
 			return path.Substring(domainUri.AbsolutePath.Length).EnsureStartsWith('/');
diff --git a/src/Umbraco.Web/Routing/IRoutesCache.cs b/src/Umbraco.Web/Routing/IRoutesCache.cs
index 0771fa556f..9033bc746e 100644
--- a/src/Umbraco.Web/Routing/IRoutesCache.cs
+++ b/src/Umbraco.Web/Routing/IRoutesCache.cs
@@ -1,19 +1,44 @@
 namespace Umbraco.Web.Routing
 {
-	// this is a bi-directional cache that contains
-	// - nodeId to route (used for NiceUrl)
-	// - route to nodeId (used for inbound requests)
-	//
-	// a route is [rootId]/path/to/node
-	// where rootId is the id of the "site root" node
-	//
-
+	/// <summary>
+	/// Represents a bi-directional cache that binds node identifiers and routes.
+	/// </summary>
+	/// <remarks>
+	/// <para>The cache is used both for inbound (map a route to a node) and outbound (map a node to a url).</para>
+	/// <para>A route is <c>[rootId]/path/to/node</c> where <c>rootId</c> is the id of the node holding an Umbraco domain, or -1.</para>
+	/// </remarks>
 	internal interface IRoutesCache
 	{
+		/// <summary>
+		/// Stores a route for a node.
+		/// </summary>
+		/// <param name="nodeId">The node identified.</param>
+		/// <param name="route">The route.</param>
 		void Store(int nodeId, string route);
+
+		/// <summary>
+		/// Gets a route for a node.
+		/// </summary>
+		/// <param name="nodeId">The node identifier.</param>
+		/// <returns>The route for the node, else null.</returns>
 		string GetRoute(int nodeId);
+
+		/// <summary>
+		/// Gets a node for a route.
+		/// </summary>
+		/// <param name="route">The route.</param>
+		/// <returns>The node identified for the route, else zero.</returns>
 		int GetNodeId(string route);
+
+		/// <summary>
+		/// Clears the route for a node.
+		/// </summary>
+		/// <param name="nodeId">The node identifier.</param>
 		void ClearNode(int nodeId);
+
+		/// <summary>
+		/// Clears all routes.
+		/// </summary>
 		void Clear();
 	}
 }
\ No newline at end of file
diff --git a/src/Umbraco.Web/Routing/NiceUrlProvider.cs b/src/Umbraco.Web/Routing/NiceUrlProvider.cs
index 00a72b264c..a124ba1d13 100644
--- a/src/Umbraco.Web/Routing/NiceUrlProvider.cs
+++ b/src/Umbraco.Web/Routing/NiceUrlProvider.cs
@@ -13,10 +13,15 @@ using umbraco.cms.businesslogic.web;
 namespace Umbraco.Web.Routing
 {
 	/// <summary>
-	/// Resolves NiceUrls for a given node id
+	/// Provides nice urls for a nodes.
 	/// </summary>
     internal class NiceUrlProvider
     {
+		/// <summary>
+		/// Initializes a new instance of the <see cref="NiceUrlProvider"/> class.
+		/// </summary>
+		/// <param name="contentStore">The content store.</param>
+		/// <param name="umbracoContext">The Umbraco context.</param>
 		public NiceUrlProvider(ContentStore contentStore, UmbracoContext umbracoContext)
         {
             _umbracoContext = umbracoContext;
@@ -104,20 +109,67 @@ namespace Umbraco.Web.Routing
 		/// Gets the nice urls of a node.
 		/// </summary>
 		/// <param name="nodeId">The node id.</param>
+		/// <param name="current">The current url.</param>
 		/// <returns>An enumeration of all valid urls for the node.</returns>
 		/// <remarks>The urls are absolute. A node can have more than one url if more than one domain is defined.</remarks>
-		public IEnumerable<string> GetNiceUrls(int nodeId)
+		public IEnumerable<string> GetNiceUrls(int nodeId, Uri current)
 		{
-			// fixme - to be implemented
-			// this is for editContent.aspx which currently has its own, highly buggy, implementation of NiceUrl...
-			throw new NotImplementedException();
+			// this is for editContent.aspx which had its own, highly buggy, implementation of NiceUrl...
+			//TODO: finalize & test implementation then replace in editContent.aspx
+
+			string path;
+			IEnumerable<Uri> domainUris;
+
+			// will not read cache if previewing!
+			var route = _umbracoContext.InPreviewMode
+				? null
+				: _umbracoContext.RoutesCache.GetRoute(nodeId);
+
+			if (route != null)
+			{
+				// route is <id>/<path> eg "-1/", "-1/foo", "123/", "123/foo/bar"...
+				int pos = route.IndexOf('/');
+				path = route.Substring(pos);
+				int id = int.Parse(route.Substring(0, pos)); // will be -1 or 1234
+				domainUris = id > 0 ? DomainUrisAtNode(id, current) : new Uri[] { };
+			}
+			else
+			{
+				var node = _contentStore.GetNodeById(nodeId);
+				if (node == null)
+					return new string[] { "#" }; // legacy wrote to the log here...
+
+				var pathParts = new List<string>();
+				int id = nodeId;
+				domainUris = DomainUrisAtNode(id, current);
+				while (!domainUris.Any() && id > 0)
+				{
+					pathParts.Add(_contentStore.GetNodeProperty(node, UrlNameProperty));
+					node = _contentStore.GetNodeParent(node);
+					id = int.Parse(_contentStore.GetNodeProperty(node, "@id")); // will be -1 or 1234
+					domainUris = id > 0 ? DomainUrisAtNode(id, current) : new Uri[] { };
+				}
+
+				// no domain, respect HideTopLevelNodeFromPath for legacy purposes
+				if (!domainUris.Any() && global::umbraco.GlobalSettings.HideTopLevelNodeFromPath)
+					pathParts.RemoveAt(pathParts.Count - 1);
+
+				pathParts.Reverse();
+				path = "/" + string.Join("/", pathParts); // will be "/" or "/foo" or "/foo/bar" etc
+				route = id.ToString() + path;
+
+				if (!_umbracoContext.InPreviewMode)
+					_umbracoContext.RoutesCache.Store(nodeId, route);
+			}
+
+			return AssembleUrls(domainUris, path, current).Select(uri => uri.ToString());
 		}
 
-		Uri AssembleUrl(Uri domain, string path, Uri current, bool absolute)
+		Uri AssembleUrl(Uri domainUri, string path, Uri current, bool absolute)
 		{
 			Uri uri;
 
-			if (domain == null)
+			if (domainUri == null)
 			{
 				// no domain was found : return a relative url,  add vdir if any
 				uri = new Uri(global::umbraco.IO.SystemDirectories.Root + path, UriKind.Relative);
@@ -126,15 +178,28 @@ namespace Umbraco.Web.Routing
 			{
 				// a domain was found : return an absolute or relative url
 				// cannot handle vdir, has to be in domain uri
-				if (!absolute && current != null && domain.GetLeftPart(UriPartial.Authority) == current.GetLeftPart(UriPartial.Authority))
-					uri = new Uri(domain.AbsolutePath.TrimEnd('/') + path, UriKind.Relative); // relative
+				if (!absolute && current != null && domainUri.GetLeftPart(UriPartial.Authority) == current.GetLeftPart(UriPartial.Authority))
+					uri = new Uri(domainUri.AbsolutePath.TrimEnd('/') + path, UriKind.Relative); // relative
 				else
-					uri = new Uri(domain.GetLeftPart(UriPartial.Path).TrimEnd('/') + path); // absolute
+					uri = new Uri(domainUri.GetLeftPart(UriPartial.Path).TrimEnd('/') + path); // absolute
 			}
 
 			return UriFromUmbraco(uri);
 		}
 
+		IEnumerable<Uri> AssembleUrls(IEnumerable<Uri> domainUris, string path, Uri current)
+		{
+			if (domainUris.Any())
+			{
+				return domainUris.Select(domainUri => new Uri(domainUri.GetLeftPart(UriPartial.Path).TrimEnd('/') + path));
+			}
+			else
+			{
+				// no domain was found : return a relative url,  add vdir if any
+				return new Uri[] { new Uri(global::umbraco.IO.SystemDirectories.Root + path, UriKind.Relative) };
+			}
+		}
+
 		Uri DomainUriAtNode(int nodeId, Uri current)
 		{
 			// be safe
@@ -142,10 +207,20 @@ namespace Umbraco.Web.Routing
 				return null;
 
 			// apply filter on domains defined on that node
-			var domainAndUri = Domains.ApplicableDomains(Domain.GetDomainsById(nodeId), current, true);
+			var domainAndUri = Domains.DomainMatch(Domain.GetDomainsById(nodeId), current, true);
 			return domainAndUri == null ? null : domainAndUri.Uri;
 		}
 
+		IEnumerable<Uri> DomainUrisAtNode(int nodeId, Uri current)
+		{
+			// be safe
+			if (nodeId <= 0)
+				return new Uri[] { };
+
+			var domainAndUris = Domains.DomainMatches(Domain.GetDomainsById(nodeId), current);
+			return domainAndUris.Select(d => d.Uri);
+		}
+
 		#endregion
 
 		#region Map public urls to/from umbraco urls
diff --git a/src/Umbraco.Web/Routing/RoutesCacheResolver.cs b/src/Umbraco.Web/Routing/RoutesCacheResolver.cs
index 98d1114866..04a49f4e66 100644
--- a/src/Umbraco.Web/Routing/RoutesCacheResolver.cs
+++ b/src/Umbraco.Web/Routing/RoutesCacheResolver.cs
@@ -3,12 +3,22 @@ using Umbraco.Core.Resolving;
 
 namespace Umbraco.Web.Routing
 {
+	/// <summary>
+	/// Resolves the <see cref="IRoutesCache"/> implementation.
+	/// </summary>
 	class RoutesCacheResolver : SingleResolverBase<RoutesCacheResolver, IRoutesCache>
 	{
+		/// <summary>
+		/// Initializes a new instance of the <see cref="RoutesCacheResolve"/> class with an <see cref="IRoutesCache"/> implementation.
+		/// </summary>
+		/// <param name="routesCache">The <see cref="IRoutesCache"/> implementation.</param>
 		internal RoutesCacheResolver(IRoutesCache routesCache)
 			: base(routesCache)
 		{ }
 
+		/// <summary>
+		/// Gets or sets the <see cref="IRoutesCache"/> implementation.
+		/// </summary>
 		public IRoutesCache RoutesCache
 		{
 			get { return this.Value; }
diff --git a/src/Umbraco.Web/Routing/RoutingContext.cs b/src/Umbraco.Web/Routing/RoutingContext.cs
index 19aa35fea8..dbb3123034 100644
--- a/src/Umbraco.Web/Routing/RoutingContext.cs
+++ b/src/Umbraco.Web/Routing/RoutingContext.cs
@@ -5,11 +5,17 @@ namespace Umbraco.Web.Routing
 {
     
 	/// <summary>
-	/// represents a request for one specified Umbraco document to be rendered by one specified template, 
-	/// using one particular culture.
+	/// Provides context for the routing of a request.
 	/// </summary>
     internal class RoutingContext
     {
+		/// <summary>
+		/// Initializes a new instance of the <see cref="RoutingContext"/> class.
+		/// </summary>
+		/// <param name="umbracoContext">The Umbraco context.</param>
+		/// <param name="documentLookupsResolver">The document lookups resolver.</param>
+		/// <param name="contentStore">The content store.</param>
+		/// <param name="niceUrlResolver">The nice urls resolver.</param>
         public RoutingContext(
 			UmbracoContext umbracoContext,
 			DocumentLookupsResolver documentLookupsResolver,
@@ -22,9 +28,24 @@ namespace Umbraco.Web.Routing
         	this.NiceUrlProvider = niceUrlResolver;
         }
 
+		/// <summary>
+		/// Gets the Umbraco context.
+		/// </summary>
 		public UmbracoContext UmbracoContext { get; private set; }
+
+		/// <summary>
+		/// Gets the document lookups resolver.
+		/// </summary>
 		public DocumentLookupsResolver DocumentLookupsResolver { get; private set; }
+
+		/// <summary>
+		/// Gets the content store.
+		/// </summary>
         public ContentStore ContentStore { get; private set; }
+
+		/// <summary>
+		/// Gets the nice urls provider.
+		/// </summary>
 		public NiceUrlProvider NiceUrlProvider { get; private set; }
     }
 }
\ No newline at end of file