Merge pull request #11455 from MoonE/apidoc-improvements

Apidoc improvements

config/jsdoc/api/template/static/scripts/main.js

@@ -36,7 +36,7 @@ $(function () {
       }
       // If everything else is equal, prefer shorter names, and prefer classes over modules
       let weight = 10000 + matchedItem.dataset.longname.length - name.length * 100;
-      if (name.match(re.begin)) {
+      if (re.begin.test(name)) {
         weight += 10000;
         if (re.baseName.test(name)) {
           weight += 10000;
@@ -79,6 +79,7 @@ $(function () {
       $currentItem: currentItem ? $(currentItem) : undefined,
       lastSearchTerm: undefined,
       lastState: {},
+      lastClasses: undefined,
       getClassList: function () {
         return $classItems || ($classItems = $navList.find('li.item'));
       },
@@ -143,9 +144,9 @@ $(function () {
       if (state === 'search-empty' && search.$currentItem) {
         search.manualToggle(search.$currentItem, true);
       }
+      search.lastClasses = undefined;
     } else {
       search.changeStateClass('searching');
-      searchTerm = searchTerm.toLowerCase();
       const beginOnly = searchTerm.length < minInputForFullText;
       const getSearchWeight = getWeightFunction(searchTerm, allowRegex);
       const re = constructRegex(searchTerm, function (searchTerm) {
@@ -197,13 +198,14 @@ $(function () {
           li.classList.add('match');
         }
       });
+      classes.sort(function (a, b) {
+        return b.weight - a.weight;
+      });
       clearOldMatches(search.lastState, searchState);
       search.lastState = searchState;
+      search.lastClasses = classes;
 
-      classes.sort(function (a, b) {
-        return a.weight - b.weight;
-      });
-      for (let i = classes.length - 1; i >= 0; --i) {
+      for (let i = 0, ii = classes.length; i < ii; ++i) {
         navList.appendChild(classes[i].item);
       }
     }
@@ -217,15 +219,24 @@ $(function () {
       key = setTimeout(function () {
         key = undefined;
 
-        const searchTerm = searchInput.value;
-        doSearch(searchTerm);
+        doSearch(searchInput.value);
       }, 0);
     }
   }
 
   // Search Items
   searchInput.addEventListener('input', queueSearch);
+  searchInput.addEventListener('keydown', function(e) {
+    if (e.key === 'Enter') {
       doSearch(searchInput.value);
+      const first = search.lastClasses ? search.lastClasses[0].item : null;
+      if (first) {
+        window.location.href = first.querySelector('.title a').href;
+      }
+    }
+  });
+  doSearch(searchInput.value);
+  searchInput.focus();
 
   // Toggle when click an item element
   search.$navList.on('click', '.toggle', function (e) {
@@ -237,10 +248,8 @@ $(function () {
     search.manualToggle(clsItem, show);
   });
 
-
-  var currentVersion = document.getElementById('package-version').innerHTML;
-
   // warn about outdated version
+  var currentVersion = document.getElementById('package-version').innerHTML;
   var packageUrl = 'https://raw.githubusercontent.com/openlayers/openlayers.github.io/build/package.json';
   fetch(packageUrl).then(function(response) {
     return response.json();
@@ -265,15 +274,4 @@ $(function () {
       }
     }
   });
-
-  // create source code links to github
-  var srcLinks = $('div.tag-source');
-  srcLinks.each(function(i, el) {
-    var textParts = el.innerHTML.trim().split(', ');
-    var link = 'https://github.com/openlayers/openlayers/blob/v' + currentVersion + '/src/ol/' +
-      textParts[0];
-    el.innerHTML = '<a href="' + link + '">' + textParts[0] + '</a>, ' +
-      '<a href="' + link + textParts[1].replace('line ', '#L') + '">' +
-      textParts[1] + '</a>';
-  });
 });

config/jsdoc/api/template/static/styles/jaguar.css

@@ -335,8 +335,8 @@ span.type-signature.static {
 }
 .main .nameContainer {
   position: relative;
-  margin-top: 20px;
-  padding-top: 5px;
+  margin-top: 1.2rem;
+  padding-top: 1.2rem;
   border-top: 2px solid #1F6B75;
 }
 .main .nameContainer .inherited {
@@ -354,7 +354,7 @@ span.type-signature.static {
 @media (min-width: 768px) {
   .main .nameContainer .tag-source {
     position: absolute;
-    top: 0.2rem;
+    top: 1.2rem;
     right: 0;
     font-size: 0.8rem;
   }

config/jsdoc/api/template/tmpl/container.tmpl

@@ -54,11 +54,15 @@
 <article>
     <div class="container-overview">
     <?js if (doc.kind === 'module' && doc.module) { ?>
+        <dl>
             <?js= self.partial('method.tmpl', doc.module) ?>
+        </dl>
     <?js } ?>
 
     <?js if (doc.kind === 'class') { ?>
+        <dl>
             <?js= self.partial('method.tmpl', doc) ?>
+        </dl>
     <?js } else { ?>
         <?js if (doc.description) { ?>
             <div class="description"><?js= doc.description ?></div>

config/jsdoc/api/template/tmpl/layout.tmpl

@@ -4,6 +4,7 @@ var version = obj.packageInfo.version;
 <!DOCTYPE html>
 <html lang="en">
   <head>
+    <meta charset="utf-8">
     <script>
     var gaProperty = 'UA-2577926-1';
     // Disable tracking if the opt-out cookie exists.
@@ -61,7 +62,6 @@ var version = obj.packageInfo.version;
       })
     });
     </script>
-    <meta charset="utf-8">
     <title>OpenLayers v<?js= version ?> API - <?js= title ?></title>
     <script src="https://cdn.polyfill.io/v2/polyfill.min.js?features=fetch"></script>
     <script src="scripts/prettify/prettify.js"> </script>

config/jsdoc/api/template/tmpl/method.tmpl

@@ -1,10 +1,16 @@
 <?js
 var data = obj;
 var self = this;
+var version = self.find({kind: 'package' })[0].version;
+if (/-dev$/.test(version)) {
+    version = 'main';
+} else {
+    version = 'v' + version;
+}
 ?>
 <dt class="<?js= (data.stability && data.stability !== 'stable') ? 'unstable' : '' ?>">
-    <div class="nameContainer<?js if (data.inherited) { ?> inherited<?js } ?>">
     <?js if (data.stability || kind !== 'class') { ?>
+    <div class="nameContainer<?js if (data.inherited) { ?> inherited<?js } ?>">
         <div class="anchor" id="<?js= id ?>">
         </div>
         <h4 class="name">
@@ -16,11 +22,12 @@ var self = this;
         </h4>
         <?js if (data.meta) {?>
         <div class="tag-source">
-            <?js= self.linkto(meta.filename) ?>, <?js= self.linkto(meta.filename, 'line ' + meta.lineno, null, 'line' + meta.lineno) ?>
+            <a href="https://github.com/openlayers/openlayers/blob/<?js= version ?>/src/ol/<?js= meta.filename ?>"><?js= meta.filename ?></a>,
+            <a href="https://github.com/openlayers/openlayers/blob/<?js= version ?>/src/ol/<?js= meta.filename ?>#L<?js= meta.lineno ?>">line <?js= meta.lineno ?></a>
         </div>
         <?js } ?>
-        <?js } ?>
     </div>
+    <?js } ?>
     <?js if (data.summary) { ?>
     <p class="summary"><?js= summary ?></p>
     <?js } ?>