Merge pull request #6010 from ggetz/experimental-jsdoc

Added experimental jsdoc tag

CHANGES.md

@@ -15,6 +15,7 @@ Change Log
 * Fixed bug in KMLDataSource.js (`processLookAt` function). Degrees and radians were mixing in a subtraction. [#5992](https://github.com/AnalyticalGraphicsInc/cesium/issues/5992)
 * Fixed handling of KMZ files with missing `xsi` namespace declarations. [#6003](https://github.com/AnalyticalGraphicsInc/cesium/pull/6003)
 * Fixed a bug where models with animations of different lengths would cause an error. [#5694](https://github.com/AnalyticalGraphicsInc/cesium/issues/5694)
+* Added a new `@experimental` tag to the documentation. A small subset of the API tagged as such are subject to breaking changes without deprecation. See the [Coding Guide](https://github.com/AnalyticalGraphicsInc/cesium/tree/master/Documentation/Contributors/CodingGuide#deprecation-and-breaking-changes) for further explanation. [#6010](https://github.com/AnalyticalGraphicsInc/cesium/pull/6010)
 * Added a `clampAnimations` parameter to `Model` and `Entity.model`. Setting this to `false` allows different length animations to loop asynchronously over the duration of the longest animation.
 
 ### 1.39 - 2017-11-01

Documentation/Contributors/CodingGuide/README.md

@@ -797,6 +797,8 @@ From release to release, we strive to keep the public Cesium API stable but also
 
 A `@private` API is considered a Cesium implementation detail and can be broken immediately without deprecation.
 
+An `@experimental` API is subject to breaking changes in future Cesium releases without deprecation. It allows for new experimental features, for instance implementing draft formats.
+
 A public identifier (class, function, property) should be deprecated before being removed.  To do so:
 
 * Decide on which future version the deprecated API should be removed.  This is on a case-by-case basis depending on how badly it impacts users and Cesium development.  Most deprecated APIs will removed in 1-3 releases.  This can be discussed in the pull request if needed.

Tools/jsdoc/cesiumTags.js

@@ -27,4 +27,14 @@ exports.defineTags = function(dictionary) {
             doclet.demo.push(tag.value);
         }
     });
+
+    dictionary.defineTag('experimental', {
+        mustHaveValue : true,
+        onTagged : function(doclet, tag) {
+            if (!doclet.experimental) {
+                doclet.experimental = [];
+            }
+            doclet.experimental.push(tag.value);
+        }
+    });
 };

Tools/jsdoc/cesium_template/static/styles/jsdoc-default.css

@@ -165,7 +165,7 @@ div.menu
     height: 35px;
 }
 
-div.nav 
+div.nav
 {
     overflow-x: hidden;
     overflow-y: auto;
@@ -211,7 +211,7 @@ div.nav div.divider
     line-height: 1.0em;
 }
 
-form 
+form
 {
     display: block;
 }
@@ -601,3 +601,17 @@ h4 .doc-link {
 h4:hover .doc-link {
     opacity: 0.7;
 }
+
+div.tag-experimental {
+    margin-left: -10px;
+    padding: 10px;
+    background-color: #ffd4a8;
+    color: #925415;
+}
+div.tag-experimental > h5 {
+    font-weight: bold;
+    margin-top: 0;
+}
+div.tag-experimental > p {
+    margin: 0 0 5px;
+}

Tools/jsdoc/cesium_template/tmpl/details.tmpl

@@ -81,6 +81,15 @@ var self = this;
     <?js }); ?></ul>
     <?js } ?>
 
+    <?js if (data.experimental && experimental.length) { ?>
+    <div class="tag-experimental">
+        <h5>Experimental</h5>
+        <?js experimental.forEach(function(e) { ?>
+            <p><?js= e ?></p>
+        <?js }); ?>
+    </div>
+    <?js } ?>
+
     <?js if (data.see && see.length) {?>
     <h5>See:</h5>
     <ul class="see-list"><?js see.forEach(function(s) { ?>