Add documentation

or some attempt at documentation

node_modules/c9/urls.js

@@ -33,9 +33,27 @@ plugin.getHost = function(req) {
 /**
  * Get a desired base URL, given some context.
  * 
- * @param req                             The current request object or URL
- * @param {String} [sourceUrlPattern]     The source URL pattern, e.g. https://ide.$DOMAIN
- * @param {String} targetBaseUrlPattern   The target URL pattern, e.g. https://$DOMAIN
+ * Example for a request coming into the IDE service:
+ * 
+ * ```
+ * getBaseUrl(req, "https://ide.$DOMAIN", "https://preview.$DOMAIN");
+ * ```
+ * 
+ * The above example will determine the domain name from the request,
+ * by stripping off the "https://ide." part. So, for a domain like
+ * "https://ide.c9.io" we'll get "c9.io". For a domain like
+ * "https://ide.dogfooding-lennartcl.c9.io" we'll get dogfooding-lennartcl.c9.io.
+ * If there is no match, a warning is shown. The target pattern
+ * is used to construct the resulting URL, e.g. https://preview.c9.io.
+ * 
+ * @param req
+ *     The current request object or URL
+ * @param {String} [sourceUrlPattern]
+ *     The URL pattern of the current service, e.g. https://ide.$DOMAIN if
+ *     we are getting an incoming request for the IDE service
+ * @param {String} targetBaseUrlPattern
+ *     The URL pattern of the target service. E.g., if we want to
+ *     construct the base URL of the API service, this might be https://api.$DOMAIN.
  */
 plugin.getBaseUrl = function(req, sourceBaseUrlPattern, targetBaseUrlPattern) {
     var sourceHost = plugin.getHost(req);