Merge pull request #78 from geops/api-docs-jsdoc

Taking over new template from jsdoc but keep modifications by OpenLayers as much as possible

Makefile

@@ -110,7 +110,7 @@ doc: build/jsdoc-$(BRANCH)-timestamp
 
 build/jsdoc-$(BRANCH)-timestamp: $(SRC) $(shell find doc/template -type f)
 	mkdir -p build/gh-pages/$(BRANCH)/apidoc
-	$(JSDOC) -t doc/template -r src -d build/gh-pages/$(BRANCH)/apidoc
+	$(JSDOC) -t doc/template -r src -d build/gh-pages/$(BRANCH)/apidoc doc/index.md
 	touch $@
 
 .PHONY: hostexamples

doc/index.md

@@ -0,0 +1,17 @@
+Finding your way round
+----------------------
+See the class list to the right and especially take a look at {@link ol.Map} and {@link ol.layer.Layer} because those are the central objects.
+
+In general every use of OpenLayers starts by initializing a map, then adding the required layers. Controls and interactions can be added to change the behavior of the map.
+
+Projections
+-----------
+A {@link ol.Projection} defines which point on earth is represented by a pair of coordinates. Coordinates within OpenLayers can be used in various projections where some common projections are always supported, others can be used via Proj4js.
+
+Maps and Layers
+---------------
+A map in OpenLayers is essentially a staple of layers that is viewed from the top. Layers are responsible for retieving data and displaying it.
+
+Contributing
+------------
+See CONTRIBUTING.md for instructions on building and tesing OpenLayers. The file does also describe how to commit your changes to OpenLayers.

doc/template/publish.js

@@ -2,6 +2,7 @@
 var template = require('jsdoc/template'),
     fs = require('fs'),
     path = require('path'),
+    taffy = require('taffydb').taffy,
     helper = require('jsdoc/util/templateHelper'),
     scopeToPunc = helper.scopeToPunc,
     hasOwnProp = Object.prototype.hasOwnProperty,
@@ -9,8 +10,9 @@ var template = require('jsdoc/template'),
     view,
     outdir = env.opts.destination;
 
-function find(spec, sort) {
-    return helper.find(data, spec, sort);
+
+function find(spec) {
+    return helper.find(data, spec);
 }
 
 function tutoriallink(tutorial) {
@@ -26,7 +28,7 @@ var linkto = helper.linkto;
 var htmlsafe = helper.htmlsafe;
 
 function hashToLink(doclet, hash) {
-    if (!/^(#.+)/.test(hash)) { return hash; }
+    if ( !/^(#.+)/.test(hash) ) { return hash; }
     
     var url = helper.createLink(doclet);
     
@@ -64,7 +66,7 @@ function generate(title, docs, filename) {
         docs: docs
     };
     
-    var outpath = outdir + '/' + filename,
+    var outpath = path.join(outdir, filename),
         html = view.render('container.tmpl', docData);
     
     html = helper.resolveLinks(html); // turn {@link foo} into <a href="foodoc.html">foo</a>
@@ -87,15 +89,28 @@ function generate(title, docs, filename) {
 function buildNav(members) {
     var nav = '<h2><a href="index.html">Index</a></h2>',
         seen = {};
-
-    function byLongName(a, b) {
-        return a.longname.localeCompare(b.longname); 
+    
+    /**
+     * Sorts elements by their qualified names (property longname).
+     * See https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array/sort
+     * @param {object} a
+     * @param {object} b
+     * @return {number}
+     */
+    function byLongName(a, b){
+        if(a.longname===b.longname){
+            return 0;
+        } else if(a.longname < b.longname){
+            return -1;
+        } else {
+            return 1;
+        }
     }
 
     if (members.modules.length) {
         nav += '<h3>Modules</h3><ul>';
         members.modules.sort(byLongName).forEach(function(m) {
-            if (!hasOwnProp.call(seen, m.longname)) {
+            if ( !hasOwnProp.call(seen, m.longname) ) {
                 nav += '<li>'+linkto(m.longname, m.longname)+'</li>';
             }
             seen[m.longname] = true;
@@ -107,8 +122,8 @@ function buildNav(members) {
     if (members.externals.length) {
         nav += '<h3>Externals</h3><ul>';
         members.externals.sort(byLongName).forEach(function(e) {
-            if (!hasOwnProp.call(seen, e.longname)) {
-                nav += '<li>'+linkto(e.longname, e.name.replace(/(^"|"$)/g, ''))+'</li>';
+            if ( !hasOwnProp.call(seen, e.longname) ) {
+                nav += '<li>'+linkto( e.longname, e.name.replace(/(^"|"$)/g, '') )+'</li>';
             }
             seen[e.longname] = true;
         });
@@ -119,7 +134,7 @@ function buildNav(members) {
     if (members.classes.length) {
         var moduleClasses = 0;
         members.classes.sort(byLongName).forEach(function(c) {
-            var moduleSameName = find({kind: 'module', longname: c.longname}, false);
+            var moduleSameName = find({kind: 'module', longname: c.longname});
             if (moduleSameName.length) {
                 c.name = c.name.replace('module:', 'require("')+'")';
                 moduleClasses++;
@@ -129,7 +144,7 @@ function buildNav(members) {
                 nav += '<h3>Classes</h3><ul>';
                 moduleClasses = -1;
             }
-            if (!hasOwnProp.call(seen, c.longname)) {
+            if ( !hasOwnProp.call(seen, c.longname) ) {
                 nav += '<li>'+linkto(c.longname, c.longname)+'</li>';
             }
             seen[c.longname] = true;
@@ -141,7 +156,7 @@ function buildNav(members) {
     if (members.namespaces.length) {
         nav += '<h3>Namespaces</h3><ul>';
         members.namespaces.sort(byLongName).forEach(function(n) {
-            if (!hasOwnProp.call(seen, n.longname)) {
+            if ( !hasOwnProp.call(seen, n.longname) ) {
                 nav += '<li>'+linkto(n.longname, n.longname)+'</li>';
             }
             seen[n.longname] = true;
@@ -153,7 +168,7 @@ function buildNav(members) {
     if (members.mixins.length) {
         nav += '<h3>Mixins</h3><ul>';
         members.mixins.sort(byLongName).forEach(function(m) {
-            if (!hasOwnProp.call(seen, m.longname)) {
+            if ( !hasOwnProp.call(seen, m.longname) ) {
                 nav += '<li>'+linkto(m.longname, m.longname)+'</li>';
             }
             seen[m.longname] = true;
@@ -174,7 +189,7 @@ function buildNav(members) {
     if (members.globals.length) {
         nav += '<h3>Global</h3><ul>';
         members.globals.sort(byLongName).forEach(function(g) {
-            if (g.kind !== 'typedef' && !hasOwnProp.call(seen, g.longname)) {
+            if ( g.kind !== 'typedef' && !hasOwnProp.call(seen, g.longname) ) {
                 nav += '<li>'+linkto(g.longname, g.longname)+'</li>';
             }
             seen[g.longname] = true;
@@ -205,9 +220,9 @@ exports.publish = function(taffyData, opts, tutorials) {
     helper.setTutorials(tutorials);
 
     data = helper.prune(data);
-    data.orderBy(['longname', 'version', 'since']);
+    data.sort('longname, version, since');
 
-    data.forEach(function(doclet) {
+    data().each(function(doclet) {
          doclet.attribs = '';
         
         if (doclet.examples) {
@@ -233,28 +248,28 @@ exports.publish = function(taffyData, opts, tutorials) {
     });
     
     // update outdir if necessary, then create outdir
-    var packageInfo = (find({kind: 'package'}, false) || []) [0];
+    var packageInfo = ( find({kind: 'package'}) || [] ) [0];
     if (packageInfo && packageInfo.name) {
-        outdir += '/' + packageInfo.name + '/' + packageInfo.version + '/';
+        outdir = path.join(outdir, packageInfo.name, packageInfo.version);
     }
     fs.mkPath(outdir);
 
     // copy static files to outdir
-    var fromDir = templatePath + '/static',
+    var fromDir = path.join(templatePath, 'static'),
         staticFiles = fs.ls(fromDir, 3);
         
     staticFiles.forEach(function(fileName) {
-        var toDir = fs.toDir(fileName.replace(fromDir, outdir));
+        var toDir = fs.toDir( fileName.replace(fromDir, outdir) );
         fs.mkPath(toDir);
         fs.copyFileSync(fileName, toDir);
     });
     
-    data.forEach(function(doclet) {
+    data().each(function(doclet) {
         var url = helper.createLink(doclet);
         helper.registerLink(doclet.longname, url);
     });
     
-    data.forEach(function(doclet) {
+    data().each(function(doclet) {
         var url = helper.longnameToUrl[doclet.longname];
 
         if (url.indexOf('#') > -1) {
@@ -272,7 +287,7 @@ exports.publish = function(taffyData, opts, tutorials) {
     });
     
     // do this after the urls have all been generated
-    data.forEach(function(doclet) {
+    data().each(function(doclet) {
         doclet.ancestors = getAncestorLinks(doclet);
 
         doclet.signature = '';
@@ -302,47 +317,45 @@ exports.publish = function(taffyData, opts, tutorials) {
     view.nav = buildNav(members);
 
     for (var longname in helper.longnameToUrl) {
-        if (hasOwnProp.call(helper.longnameToUrl, longname)) {
+        if ( hasOwnProp.call(helper.longnameToUrl, longname) ) {
             // reuse 'members', which speeds things up a bit
-            var classes = new (require('typicaljoe/taffy'))(members.classes);
-            classes = helper.find(classes, {longname: longname}, false);
+            var classes = taffy(members.classes);
+            classes = helper.find(classes, {longname: longname});
             if (classes.length) {
                 generate('Class: ' + classes[0].longname, classes, helper.longnameToUrl[longname]);
             }
     
-            var modules = new (require('typicaljoe/taffy'))(members.modules);
-            modules = helper.find(modules, {longname: longname}, false);
+            var modules = taffy(members.modules);
+            modules = helper.find(modules, {longname: longname});
             if (modules.length) {
                 generate('Module: ' + modules[0].longname, modules, helper.longnameToUrl[longname]);
             }
         
-            var namespaces = new (require('typicaljoe/taffy'))(members.namespaces);
-            namespaces = helper.find(namespaces, {longname: longname}, false);
+            var namespaces = taffy(members.namespaces);
+            namespaces = helper.find(namespaces, {longname: longname});
             if (namespaces.length) {
                 generate('Namespace: ' + namespaces[0].longname, namespaces, helper.longnameToUrl[longname]);
             }
         
-            var mixins = new (require('typicaljoe/taffy'))(members.mixins);
-            mixins = helper.find(mixins, {longname: longname}, false);
+            var mixins = taffy(members.mixins);
+            mixins = helper.find(mixins, {longname: longname});
             if (mixins.length) {
                 generate('Mixin: ' + mixins[0].longname, mixins, helper.longnameToUrl[longname]);
             }
     
-            var externals = new (require('typicaljoe/taffy'))(members.externals);
-            externals = helper.find(externals, {longname: longname}, false);
+            var externals = taffy(members.externals);
+            externals = helper.find(externals, {longname: longname});
             if (externals.length) {
                 generate('External: ' + externals[0].longname, externals, helper.longnameToUrl[longname]);
             }
         }
     }
 
-    if (members.globals.length) { 
-        generate('Global', [{kind: 'globalobj'}], 'global.html'); 
-    }
+    if (members.globals.length) { generate('Global', members.globals, 'global.html'); }
     
     // index page displays information from package.json and lists files
-    var files = find({kind: 'file'}, false),
-        packages = find({kind: 'package'}, false);
+    var files = find({kind: 'file'}),
+        packages = find({kind: 'package'});
 
     generate('Index',
 		packages.concat(
@@ -359,7 +372,7 @@ exports.publish = function(taffyData, opts, tutorials) {
             children: tutorial.children
         };
         
-        var tutorialPath = outdir + '/' + filename,
+        var tutorialPath = path.join(outdir, filename),
             html = view.render('tutorial.tmpl', tutorialData);
         
         // yes, you can use {@link} in tutorials too!

doc/template/static/styles/jsdoc-default.css

@@ -1,9 +1,11 @@
-html {
+html
+{
     overflow: auto;
     background-color: #fff;
 }
 
-body {
+body
+{
 	font: 14px "DejaVu Sans Condensed", "Liberation Sans", "Nimbus Sans L", Tahoma, Geneva, "Helvetica Neue", Helvetica, Arial, sans serif;
 	line-height: 130%;
 	color: #000;
@@ -22,7 +24,8 @@ a:active {
     color: #444;
 }
 
-header {
+header
+{
 	display: block;
 	padding: 6px 4px;
 }
@@ -41,7 +44,8 @@ header {
     width: 100%;
 }
 
-section {
+section
+{
 	display: block;
 	
 	background-color: #fff;
@@ -62,7 +66,8 @@ section {
 	font-weight: lighter;
 }
 
-nav {
+nav
+{
 	display: block;
 	float: left;
     margin-left: -230px;
@@ -114,21 +119,24 @@ footer {
     font-size: 90%;
 }
 
-h1 {
+h1
+{
 	font-size: 200%;
 	font-weight: bold;
 	letter-spacing: -0.01em;
 	margin: 6px 0 9px 0;
 }
 
-h2 {
+h2
+{
 	font-size: 170%;
 	font-weight: bold;
 	letter-spacing: -0.01em;
 	margin: 6px 0 3px 0;
 }
 
-h3 {
+h3
+{
 	font-size: 150%;
 	font-weight: bold;
 	letter-spacing: -0.01em;
@@ -136,7 +144,8 @@ h3 {
 	margin: 6px 0 3px 0;
 }
 
-h4 {
+h4
+{
 	font-size: 130%;
 	font-weight: bold;
 	letter-spacing: -0.01em;
@@ -145,14 +154,16 @@ h4 {
 	color: #A35A00;
 }
 
-h5, .container-overview .subsection-title {
+h5, .container-overview .subsection-title
+{
 	font-size: 120%;
 	font-weight: bold;
 	letter-spacing: -0.01em;
 	margin: 8px 0 3px -16px;
 }
 
-h6 {
+h6
+{
 	font-size: 100%;
 	letter-spacing: -0.01em;
 	margin: 6px 0 3px 0;
@@ -162,18 +173,19 @@ h6 {
 .protected {
     display: none;
 }
-
 dt.tag-source, dd.tag-source {
     display: none;
 }
 
 .ancestors { color: #999; }
-.ancestors a {
+.ancestors a
+{
     color: #999 !important;
     text-decoration: none;
 }
 
-.important {
+.important
+{
 	font-weight: bold;
 	color: #950B02;
 }
@@ -203,19 +215,22 @@ dt.tag-source, dd.tag-source {
 	margin-top: 1em;
 }
 
-.code-caption {
+.code-caption
+{
 	font-style: italic;
 	font-family: Palatino, 'Palatino Linotype', serif;
 	font-size: 107%;
 	margin: 0;
 }
 
-.prettyprint {
+.prettyprint
+{
 	border: 1px solid #ddd;
 	width: 80%;
 }
 
-.prettyprint code {
+.prettyprint code
+{
 	font-family: Consolas, 'Lucida Console', Monaco, monospace;
 	font-size: 100%;
 	line-height: 18px;
@@ -227,7 +242,8 @@ dt.tag-source, dd.tag-source {
 	border-left: 3px #ddd solid;
 }
 
-.params, .props {
+.params, .props
+{
 	border-spacing: 0;
 	border: 0;
 	border-collapse: collapse;
@@ -239,7 +255,8 @@ dt.tag-source, dd.tag-source {
 	font-size: 100%;
 }
 
-.params td, .params th, .props td, .props th {
+.params td, .params th, .props td, .props th
+{
 	border: 1px solid #ddd;
 	margin: 0px;
 	text-align: left;
@@ -248,12 +265,14 @@ dt.tag-source, dd.tag-source {
 	display: table-cell;
 }
 
-.params thead tr, .props thead tr {
+.params thead tr, .props thead tr
+{
 	background-color: #ddd;
 	font-weight: bold;
 }
 
-.params .params thead tr, .props .props thead tr {
+.params .params thead tr, .props .props thead tr
+{
 	background-color: #fff;
 	font-weight: bold;
 }

doc/template/tmpl/details.tmpl

@@ -1,4 +1,7 @@
-<?js var self = this; ?>
+<?js
+var data = obj;
+var self = this;
+?>
 <dl class="details">
     <?js
         var properties = data.properties;

doc/template/tmpl/example.tmpl

@@ -1,2 +1,2 @@
-
+<?js var data = obj; ?>
 <pre><code><?js= data ?></code></pre>

doc/template/tmpl/examples.tmpl

@@ -1,4 +1,5 @@
 <?js
+	var data = obj;
     data.forEach(function(example) {
         if (example.caption) {
     ?>

doc/template/tmpl/exceptions.tmpl

@@ -1,4 +1,7 @@
-<?js if (data.description) { ?>
+<?js
+	var data = obj;
+	if (data.description) {
+?>
 <div class="param-desc">
     <?js= description ?>
 </div>

doc/template/tmpl/fires.tmpl

@@ -1,3 +1,4 @@
+<?js var data = obj; ?>
 <li>
     <?js= data ?>
 </li>

doc/template/tmpl/layout.tmpl

@@ -2,7 +2,7 @@
 <html lang="en">
 <head>
     <meta charset="utf-8">
-    <title>OpenLayers <?js= title ?></title>
+    <title>OpenLayers: <?js= title ?></title>
     
     <script src="scripts/prettify/prettify.js"> </script>
     <script src="scripts/prettify/lang-css.js"> </script>
@@ -10,7 +10,7 @@
       <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
     <![endif]-->
     <link type="text/css" rel="stylesheet" href="styles/prettify-jsdoc.css">
-    <link type="text/css" rel="stylesheet" href="styles/apidoc.css">
+    <link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css">
 </head>
 
 <body>

doc/template/tmpl/mainpage.tmpl

@@ -1,4 +1,5 @@
 <?js
+var data = obj;
 var self = this;
 ?>
 

doc/template/tmpl/members.tmpl

@@ -1,12 +1,12 @@
-
-<dt class="protected">
+<?js var data = obj; ?>
+<dt class="<?js= data.access ?>">
     <h4 class="name" id="<?js= id ?>"><?js= data.attribs + name + data.signature ?></h4>
     
     <?js if (data.summary) { ?>
     <p class="summary"><?js= summary ?></p>
     <?js } ?>
 </dt>
-<dd class="protected">
+<dd class="<?js= data.access ?>">
     <?js if (data.description) { ?>
     <div class="description">
         <?js= data.description ?>

doc/template/tmpl/method.tmpl

@@ -1,4 +1,7 @@
-<?js var self = this; ?>
+<?js
+var data = obj;
+var self = this;
+?>
 <dt>
     <h4 class="name" id="<?js= id ?>"><?js= data.attribs + (kind == 'class'? 'new ':'') + name + data.signature ?></h4>
     

doc/template/tmpl/params.tmpl

@@ -1,5 +1,5 @@
 <?js
-    var params = data;
+    var params = obj;
     
     /* sort subparams under their parent params (like opts.classname) */
     var parentParam = null;
@@ -47,6 +47,10 @@
 		
 		<th>Type</th>
 		
+		<?js if (params.hasAttributes) {?>
+		<th>Argument</th>
+		<?js } ?>
+		
 		<?js if (params.hasDefault) {?>
 		<th>Default</th>
 		<?js } ?>
@@ -73,6 +77,18 @@
             <?js } ?>
             </td>
             
+            <?js if (params.hasAttributes) {?>
+                <td class="attributes">
+                <?js if (param.optional) { ?>
+                    &lt;optional><br>
+                <?js } ?>
+                    
+                <?js if (param.nullable) { ?>
+                    &lt;nullable><br>
+                <?js } ?>
+                </td>
+            <?js } ?>
+            
             <?js if (params.hasDefault) {?>
                 <td class="default">
                 <?js if (typeof param.defaultvalue !== 'undefined') { ?>

doc/template/tmpl/properties.tmpl

@@ -1,5 +1,5 @@
 <?js
-    var props = data;
+    var props = obj;
     
     /* sort subprops under their parent props (like opts.classname) */
     var parentProp = null;

doc/template/tmpl/returns.tmpl

@@ -1,4 +1,7 @@
-<?js if (data.description) { ?>
+<?js
+var data = obj;
+if (data.description) {
+?>
 <div class="param-desc">
     <?js= description ?>
 </div>

doc/template/tmpl/type.tmpl

@@ -1,4 +1,5 @@
 <?js
+	var data = obj;
     var self = this;
     data.forEach(function(name, i) { ?>
 <span class="param-type"><?js= self.linkto(name, self.htmlsafe(name)) ?></span>