Added experimental jsdoc tag

CHANGES.md

@@ -11,6 +11,7 @@ Change Log
 * Fixed bug in KMLDataSource.js (`processLookAt` function). Degrees and radians were mixing in a subtraction. [#5992](https:/AnalyticalGraphicsInc/cesium/issues/5992)
 * Fixed handling of KMZ files with missing `xsi` namespace declarations. [#6003](https:/AnalyticalGraphicsInc/cesium/pull/6003)
 * Fixed a bug where models with animations of different lengths would cause an error. [#5694](https:/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:/AnalyticalGraphicsInc/cesium/tree/master/Documentation/Contributors/CodingGuide#deprecation-and-breaking-changes) for further explanation. [#6010](https:/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) { ?>