From fedceb9a05e220784c1ff44716733ea40eac644c Mon Sep 17 00:00:00 2001
From: Marc Jansen <jansen@terrestris.de>
Date: Mon, 13 Apr 2015 23:49:24 +0200
Subject: [PATCH 1/2] Automatically add links to API-docs in examples
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

When we create the examples, we know exactly which specific `ol.…` symbols
we `goog.require(…)`. We can create links to the API documentation of these
symbols automatically.
---
 config/examples/example.html  |  1 +
 examples/resources/layout.css |  3 +++
 tasks/build-examples.js       | 41 +++++++++++++++++++++++++++++++++--
 3 files changed, 43 insertions(+), 2 deletions(-)

diff --git a/config/examples/example.html b/config/examples/example.html
index eea96c02b4..fa52d8e50d 100644
--- a/config/examples/example.html
+++ b/config/examples/example.html
@@ -33,6 +33,7 @@
           <p id="shortdesc">{{ shortdesc }}</p>
           <div id="docs">{{ md docs }}</div>
           <div id="tags">{{ tags }}</div>
+          <div id="api-links">Related API documentation: {{{ js.apiHtml }}}</div>
         </div>
       </div>
 
diff --git a/examples/resources/layout.css b/examples/resources/layout.css
index a0daef1002..066bcc5021 100644
--- a/examples/resources/layout.css
+++ b/examples/resources/layout.css
@@ -18,6 +18,9 @@ body {
 #tags, #shortdesc, .hidden {
   display: none;
 }
+#api-links ul {
+  display: inline;
+}
 
 body, h1, h2, h3, h4, p, li, td, th {
   font-family: Quattrocento Sans;
diff --git a/tasks/build-examples.js b/tasks/build-examples.js
index 212b8c04e3..b8bb463166 100644
--- a/tasks/build-examples.js
+++ b/tasks/build-examples.js
@@ -8,6 +8,7 @@ var pkg = require('../package.json');
 
 var markupRegEx = /([^\/^\.]*)\.html$/;
 var cleanupJSRegEx = /.*(goog\.require(.*);|.*renderer: common\..*,?)[\n]*/g;
+var googRequiresRegEx = /.*goog\.require\('(ol\.\S*)'\);/g;
 var isCssRegEx = /\.css$/;
 var isJsRegEx = /\.js$/;
 
@@ -15,6 +16,41 @@ var srcDir = path.join(__dirname, '..', 'examples');
 var destDir = path.join(__dirname, '..', 'build', 'examples');
 var templatesDir = path.join(__dirname, '..', 'config', 'examples');
 
+/**
+ * Returns an array of classes that are explicitly required inside the source
+ * by calling 'goog.require(…)'
+ *
+ * @param {string} src The JavaScript sourcecode to search for goog.require.
+ * @returns {Array.<string>} An array of ol-classes that the source requires.
+ */
+function getGoogRequires(src) {
+  var googRequires = [];
+  var match = googRequiresRegEx.exec(src);
+  while (match) {
+    googRequires.push(match[1]);
+    match = googRequiresRegEx.exec(src);
+  }
+  return googRequires;
+}
+
+/**
+ * Takes an array of the names of required OpenLayers symbols and returns an
+ * HTML-snippet with an unordered list to the API-docs for the particular
+ * classes.
+ *
+ * @param {Array.<string>} googRequires An array of ol-classes that the source
+ *   requires.
+ * @returns {string} The HTML-snippet with the list of links to API-docs.
+ */
+function getLinkToApiHtml(googRequires) {
+  var lis = googRequires.map(function(symb) {
+    var href = '../apidoc/' + symb + '.html';
+    return '<li><a href="' + href + '" title="API documentation for ' +
+        symb +'">' + symb + '</a></li>';
+  });
+  return '<ul class="inline">' + lis.join() + '</ul>';
+}
+
 /**
  * A Metalsmith plugin that adds metadata to the example HTML files.  For each
  * example HTML file, this adds metadata for related js and css resources. When
@@ -46,10 +82,11 @@ function augmentExamples(files, metalsmith, done) {
       if (!(jsFilename in files)) {
         throw new Error('No .js file found for ' + filename);
       }
+      var jsSource = files[jsFilename].contents.toString();
       file.js = {
         tag: '<script src="loader.js?id=' + id + '"></script>',
-        source: files[jsFilename].contents.toString().replace(
-            cleanupJSRegEx, '')
+        source: jsSource.replace(cleanupJSRegEx, ''),
+        apiHtml: getLinkToApiHtml(getGoogRequires(jsSource))
       };
 
       // add css tag and source

From 0fcd312812536b7f8defd72b57675db0bb96d227 Mon Sep 17 00:00:00 2001
From: Marc Jansen <jansen@terrestris.de>
Date: Fri, 17 Apr 2015 19:31:02 +0200
Subject: [PATCH 2/2] Check if API-docs point to existing resources

---
 examples/resources/common.js | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/examples/resources/common.js b/examples/resources/common.js
index 2609dbbd7c..c731a39b59 100644
--- a/examples/resources/common.js
+++ b/examples/resources/common.js
@@ -10,6 +10,31 @@
     });
   }
 
+  // Check whether links to API-docs of used classes actually point to
+  // existing html-files:
+  $('#api-links a').each(function() {
+    var url = this.href;
+    $.ajax({
+      type: 'HEAD',
+      url: url,
+      context: this,
+      error: function() {
+        // We get into the error if either the resource didn't exist
+        // or if HEAD was not allowed (when serving locally via node)
+        // => remove the <li> and the following comma
+        var li = $(this).parent();
+        var comma = $(li[0].nextSibling);
+        comma.remove();
+        li.remove();
+        // It may be that this was the last <li>, if that's the case,
+        // remove the complete <div>, as we don't have an API-links
+        if ($('#api-links li').length === 0) {
+          $('#api-links').remove();
+        }
+      }
+    });
+  });
+
   if (window.location.host === 'localhost:3000') {
     return;
   }