chore(_util-fns): generalize makeExample, drop makeProjExample (#1510)

+ Rename adjustExample{Path|Title} to adjustTsExample*4Dart
+ `makeExample` can now work with both doc folder relative and project
relative paths.

Author: chalin

public/_includes/_util-fns.jade

@@ -53,10 +53,10 @@ mixin ifDocsFor(langPattern)
     block
 
 //- Use to map inlined (prose) TS paths into, say, Dart paths via the
-//- adjustExamplePath transformer function.
+//- adjustTsExamplePathForDart transformer function.
 mixin adjExPath(path)
-  if adjustExamplePath
-    | #{adjustExamplePath(path)}
+  if adjustTsExamplePathForDart
+    | #{adjustTsExamplePathForDart(path)}
   else
     | #{path}
 
@@ -65,8 +65,9 @@ mixin includeShared(filePath, region)
   !=partial(newPath)
 
 mixin makeExample(_filePath, region, _title, stylePatterns)
-  - var filePath = adjustExamplePath ? adjustExamplePath(_filePath) : _filePath;
-  - var title = adjustExampleTitle ? adjustExampleTitle(_title) : _title;
+  - var adjustments = adjustExamplePathAndTitle({filePath:_filePath, title:_title});
+  - var filePath = adjustments.filePath;
+  - var title = adjustments.title;
   - var language = attributes.language || getExtn(filePath);
   - var frag = getFrag(filePath, region);
   - var defaultFormat = frag.split('\n').length > 2 ? "linenums" : "";
@@ -82,35 +83,21 @@ mixin makeExample(_filePath, region, _title, stylePatterns)
   code-example(language="#{language}" format="#{format}")
     != styleString(frag, stylePatterns)
 
-//- Like makeExample, but the first argument is a path that is
-//- relative to the project root. Unless title is defined,
-//- the project relative path will be used.
-mixin makeProjExample(projRootRelativePath, region, title, stylePatterns)
-  - var relPath = projRootRelativePath.trim();
-  - var filePath = getExampleName() + '/ts/' + relPath;
-  - if (!title) {
-  -   // Is path like styles.1.css? Then drop the '.1' qualifier:
-  -   var matches = relPath.match(/^(.*)\.\d(\.\w+)$/);
-  -   title = matches ? matches[1] + matches[2] : relPath;
-  - }
-  +makeExample(filePath, region, title, stylePatterns)
-
-//- Like makeExample, but doesn't show line numbers, and the first
-//- argument is a path that is relative to the example project root.
-//- Unless title is defined, the project relative path will be used.
-//- Title will always end with a phrase in parentheses; if no such
-//- ending is given, then the title will be suffixed with
-//- either "(excerpt)", or "(#{region})" when region is defined.
-mixin makeExcerpt(projRootRelativePath, region, title, stylePatterns)
-  - var relPath = projRootRelativePath.trim();
-  - var filePath = getExampleName() + '/ts/' + relPath;
-  - if (!title) {
-  -   // Is path like styles.1.css? Then drop the '.1' qualifier:
-  -   var matches = relPath.match(/^(.*)\.\d(\.\w+)$/);
-  -   title = matches ? matches[1] + matches[2] : relPath;
-  - }
-  - var excerpt = region || 'excerpt';
-  - if (title && !title.match(/\([\w ]+\)$/)) title = title + ' (' + excerpt + ')';
+//- Like makeExample, but: (1) doesn't show line numbers. (2) If region
+//- is omitted and title is 'foo (r)' then region is taken as 'r'.
+//- (3) Title will always end with a phrase in parentheses; if no such
+//- ending is given or is just (), then the title will be suffixed with
+//- either "(excerpt)", or "(#{_region})" when _region is defined.
+mixin makeExcerpt(_filePath, _region, _title, stylePatterns)
+  - var matches = _filePath.match(/(.*)\s+\(([\w ]*)\)$/);
+  - var parenText;
+  - if (matches) { _filePath = matches[1]; parenText = matches[2]; }
+  - var adjustments = adjustExamplePathAndTitle({filePath:_filePath, title:_title});
+  - var filePath = adjustments.filePath;
+  - var title = adjustments.title;
+  - var region = _region || parenText;
+  - var excerpt = !region || parenText === '' ? 'excerpt' : region;
+  - if (title) title = title + ' (' + excerpt + ')';
   +makeExample(filePath, region, title, stylePatterns)(format='.')
 
 //- Extract the doc example name from `current`.
@@ -121,10 +108,10 @@ mixin makeExcerpt(projRootRelativePath, region, title, stylePatterns)
 
 mixin makeTabs(filePaths, regions, tabNames, stylePatterns)
   - filePaths = strSplit(filePaths);
-  - if (adjustExamplePath) filePaths = filePaths.map(adjustExamplePath);
+  - if (adjustTsExamplePathForDart) filePaths = filePaths.map(adjustTsExamplePathForDart);
   - regions = strSplit(regions, filePaths.length);
   - tabNames = strSplit(tabNames, filePaths.length);
-  - if (adjustExampleTitle) tabNames = tabNames.map(adjustExampleTitle);
+  - if (adjustTsExampleTitleForDart) tabNames = tabNames.map(adjustTsExampleTitleForDart);
 
   code-tabs
       each filePath,index in filePaths
@@ -216,6 +203,43 @@ script.
       return CCSstyle[style] = value
   }
 //---------------------------------------------------------------------------------------------------------
+//- Converts the given project-relative path (like 'app/main.ts')
+//- to a doc folder relative path (like 'quickstart/ts/app/main.ts')
+//- by prefixing it with '<example-name>/ts/'. If title is not given,
+//- then the project-relative path is used, adjusted to remove numeric
+//- file version qualifiers; e.g. 'styles.1.css' becomes 'styles.css'.
+- var adjExampleProjPathAndTitle = function(ex/*:{filePath,title}*/) {
+-   // E.g. of a project relative path is 'app/main.ts'
+-   if (ex.title === null || ex.title === undefined) {
+-     // Title is not given so take it to be ex.filePath.
+-     // Is title like styles.1.css? Then drop the '.1' qualifier:
+-     var matches = ex.filePath.match(/^(.*)\.\d(\.\w+)$/);
+-     ex.title = matches ? matches[1] + matches[2] : ex.filePath;
+-   }
+-   ex.filePath = getExampleName() + '/' + _docsFor + '/' + ex.filePath;
+-   return ex;
+- };
+
+//- If the given path is project relative, then first convert it using
+//- adjExampleProjPathAndTitle(ex). Then the path is adjusted to match
+//- the documentation language.
+- var adjustExamplePathAndTitle = function(ex/*:{filePath,title}*/) {
+-   // Not a doc folder relative path? Assume that it is app project relative.
+-   if(isProjRelDir(ex.filePath)) adjExampleProjPathAndTitle(ex);
+-   // Adjust doc folder relative paths if adjustment functions exist.
+-   if(adjustTsExamplePathForDart) ex.filePath = adjustTsExamplePathForDart(ex.filePath);
+-   if(adjustTsExampleTitleForDart) ex.title = adjustTsExampleTitleForDart(ex.title);
+-   return ex;
+- };
+
+//- Returns truthy iff path is example project relative.
+- var isProjRelDir = function(path) {
+-   return !path.match(/\/(js|ts|dart)(-snippets)?\//) && !path.endsWith('e2e-spec.js');
+-   // Last conjunct handles case for shared project e2e test file like
+-   // cb-component-communication/e2e-spec.js (is shared between ts & dart)
+-   // TODO: generalize: compare start with getExampleName(); which needs to be fixed.
+- };
+
 - var translatePath = function(filePath, region) {
 -   filePath = filePath.trim();
 -   var regionPad = (region && region.length) ? '-' + region.toString() : '';

public/docs/dart/latest/_util-fns.jade

@@ -32,7 +32,7 @@ mixin liveExampleLink2(linkText, exampleUrlPartName)
   - var href = 'http://github.com/angular-examples/' + ex;
   span #[+liveExampleLink(linkText, ex)] (#[a(href='#{href}' target="_blank") #{srcText}])
 
-- var adjustExamplePath = function(_path) {
+- var adjustTsExamplePathForDart = function(_path) {
 -   if(!_path) return _path;
 -   var path = _path.trim();
 -   var folder = getFolder(path);
@@ -52,15 +52,15 @@ mixin liveExampleLink2(linkText, exampleUrlPartName)
 -   return (folder ? folder + '/' : '') + baseNameNoExt + (extn ? '.' + extn : '');
 - };
 
-- var adjustExampleTitle = function(_title) {
--   if(!_title || !adjustExamplePath) return _title;
+- var adjustTsExampleTitleForDart = function(_title) {
+-   if(!_title || !adjustTsExamplePathForDart) return _title;
 -   var title = _title.trim();
 -   // Assume title is a path if it ends with an extension like '.foo',
 -   // optionally followed by some comment in parentheses.
 -   var matches = title.match(/(.*\.\w+)($|\s*\([\w ]+\)$)/);
 -   if(matches && matches.length == 3) {
 -     // e.g. matches == ['abc.ts (excerpt)', 'abc.ts', ' (excerpt)']
--     var path = adjustExamplePath(matches[1]);
+-     var path = adjustTsExamplePathForDart(matches[1]);
 -     title = path + matches[2];
 -   }
 -   return title;

public/docs/dart/latest/guide/server-communication.jade

@@ -35,7 +35,7 @@ block http-providers
     [ng2dtri]: https://github.com/angular/angular/wiki/Angular-2-Dart-Transformer#resolved_identifiers
 
   - var stylePattern = { pnk: /(resolved_identifiers:|Browser.*)/gm, otl: /(- angular2:)|(transformers:)/g };
-  +makeExcerpt('pubspec.yaml', 'transformers', 'pubspec.yaml (transformers)', stylePattern)
+  +makeExcerpt('pubspec.yaml', 'transformers', null, stylePattern)
 
 block getheroes-and-addhero
   :marked

public/docs/ts/latest/quickstart.jade

@@ -211,7 +211,7 @@ p.
   #[b Create the component file]
   #[code #[+adjExPath('app/app.component.ts')]] (in this newly created directory) with the following content:
 
-+makeProjExample('app/app.component.ts')
++makeExample('app/app.component.ts')
 
 .l-verbose-section
   :marked
@@ -300,7 +300,7 @@ block create-main
     Now we need something to tell Angular to load the root component.
     Create the file #[code #[+adjExPath('app/main.ts')]] with the following content:
 
-+makeProjExample('app/main.ts')
++makeExample('app/main.ts')
 
 .l-verbose-section
   :marked
@@ -345,7 +345,7 @@ h2#index Step 4: Add #[code index.html]
   In the *#{_indexHtmlDir}* folder
   create an `index.html` file and paste the following lines into it:
 
-+makeProjExample('index.html')
++makeExample('index.html')
 
 .l-verbose-section
   :marked