Merge pull request #11362 from rwjblue/enforce-documentation-access-s…

…pecifics

[DOC beta] Enforce public/private declaration for API docs.

.jscsrc

@@ -56,5 +56,6 @@
   "requireSpacesAfterClosingParenthesisInFunctionDeclaration": {
     "beforeOpeningRoundBrace": false,
     "beforeOpeningCurlyBrace": true
-  }
+  },
+  "requireCommentsToIncludeAccess": true
 }

lib/jscs-rules/require-comments-to-include-access.js

@@ -0,0 +1,38 @@
+var assert = require('assert');
+
+function isDocComment(comment) {
+  return comment.value[0] === '*';
+}
+
+function isModuleOnlyComment(comment) {
+  return comment.value.match(/^\*\n\s*@module.+\n(?:\s*@submodule.+\n)?$/);
+}
+
+function includesAccessDeclaration(comment) {
+  return comment.value.match(/\n\s*(@private|@public)\s/);
+}
+
+function RequireCommentsToIncludeAccess() { }
+
+RequireCommentsToIncludeAccess.prototype = {
+  configure: function(value) {
+    assert(
+      value === true,
+      this.getOptionName() + ' option requires a true value or should be removed'
+    );
+  },
+
+  getOptionName: function() {
+    return 'requireCommentsToIncludeAccess';
+  },
+
+  check: function(file, errors) {
+    file.iterateTokensByType('Block', function(comment) {
+      if (isDocComment(comment) && !isModuleOnlyComment(comment) && !includesAccessDeclaration(comment)) {
+        errors.add('You must supply `@public` or `@private` for block comments.', comment.loc.end);
+      }
+    });
+  }
+};
+
+module.exports = RequireCommentsToIncludeAccess;

packages/container/lib/container.js

@@ -45,18 +45,22 @@ Container.prototype = {
   _registry: null,
 
   /**
+   @private
+
    @property cache
    @type InheritingDict
    */
   cache: null,
 
   /**
+   @private
    @property factoryCache
    @type InheritingDict
    */
   factoryCache: null,
 
   /**
+   @private
    @property validationCache
    @type InheritingDict
    */
@@ -100,6 +104,7 @@ Container.prototype = {
    twitter === twitter2; //=> false
    ```
 
+   @private
    @method lookup
    @param {String} fullName
    @param {Object} options
@@ -113,6 +118,7 @@ Container.prototype = {
   /**
    Given a fullName return the corresponding factory.
 
+   @private
    @method lookupFactory
    @param {String} fullName
    @return {any}
@@ -126,6 +132,7 @@ Container.prototype = {
    A depth first traversal, destroying the container, its descendant containers and all
    their managed objects.
 
+   @private
    @method destroy
    */
   destroy() {
@@ -141,6 +148,7 @@ Container.prototype = {
   /**
    Clear either the entire cache or just the cache for a particular key.
 
+   @private
    @method reset
    @param {String} fullName optional key to reset; if missing, resets everything
    */

packages/container/lib/registry.js

@@ -47,18 +47,21 @@ Registry.prototype = {
   /**
    A backup registry for resolving registrations when no matches can be found.
 
+   @private
    @property fallback
    @type Registry
    */
   fallback: null,
 
   /**
+   @private
    @property resolver
    @type function
    */
   resolver: null,
 
   /**
+   @private
    @property registrations
    @type InheritingDict
    */
@@ -143,6 +146,7 @@ Registry.prototype = {
   /**
    Creates a container based on this registry.
 
+   @private
    @method container
    @param {Object} options
    @return {Container} created container
@@ -164,6 +168,7 @@ Registry.prototype = {
    2.0TODO: Remove this method. The bookkeeping is only needed to support
             deprecated behavior.
 
+   @private
    @param {Container} newly created container
    */
   registerContainer(container) {
@@ -208,6 +213,7 @@ Registry.prototype = {
    registry.register('communication:main', Email, {singleton: false});
    ```
 
+   @private
    @method register
    @param {String} fullName
    @param {Function} factory
@@ -244,6 +250,7 @@ Registry.prototype = {
    registry.resolve('model:user') === undefined //=> true
    ```
 
+   @private
    @method unregister
    @param {String} fullName
    */
@@ -286,6 +293,7 @@ Registry.prototype = {
    registry.resolve('api:twitter') // => Twitter
    ```
 
+   @private
    @method resolve
    @param {String} fullName
    @return {Function} fullName's factory
@@ -307,6 +315,7 @@ Registry.prototype = {
    class name (including namespace) where Ember's resolver expects
    to find the `fullName`.
 
+   @private
    @method describe
    @param {String} fullName
    @return {string} described fullName
@@ -318,6 +327,7 @@ Registry.prototype = {
   /**
    A hook to enable custom fullName normalization behaviour
 
+   @private
    @method normalizeFullName
    @param {String} fullName
    @return {string} normalized fullName
@@ -329,6 +339,7 @@ Registry.prototype = {
   /**
    normalize a fullName based on the applications conventions
 
+   @private
    @method normalize
    @param {String} fullName
    @return {string} normalized fullName
@@ -342,6 +353,7 @@ Registry.prototype = {
   /**
    @method makeToString
 
+   @private
    @param {any} factory
    @param {string} fullName
    @return {function} toString function
@@ -354,6 +366,7 @@ Registry.prototype = {
    Given a fullName check if the container is aware of its factory
    or singleton instance.
 
+   @private
    @method has
    @param {String} fullName
    @return {Boolean}
@@ -387,6 +400,7 @@ Registry.prototype = {
    facebook === facebook2; // => false
    ```
 
+   @private
    @method optionsForType
    @param {String} type
    @param {Object} options
@@ -404,6 +418,7 @@ Registry.prototype = {
   },
 
   /**
+   @private
    @method options
    @param {String} fullName
    @param {Object} options
@@ -540,6 +555,7 @@ Registry.prototype = {
    user.source === post.source; //=> true
    ```
 
+   @private
    @method injection
    @param {String} factoryName
    @param {String} property
@@ -650,6 +666,7 @@ Registry.prototype = {
    UserFactory.store === PostFactory.store; //=> true
    ```
 
+   @private
    @method factoryInjection
    @param {String} factoryName
    @param {String} property

packages/ember-application/lib/ext/controller.js

@@ -1,6 +1,7 @@
 /**
 @module ember
 @submodule ember-application
+@public
 */
 
 import Ember from "ember-metal/core"; // Ember.assert
@@ -70,6 +71,7 @@ var defaultControllersComputedProperty = computed(function() {
 /**
   @class ControllerMixin
   @namespace Ember
+  @public
 */
 ControllerMixin.reopen({
   concatenatedProperties: ['needs'],
@@ -118,8 +120,10 @@ ControllerMixin.reopen({
 
     This is only available for singleton controllers.
 
+    @deprecated Use `Ember.inject.controller()` instead.
     @property {Array} needs
     @default []
+    @public
   */
   needs: [],
 
@@ -148,6 +152,7 @@ ControllerMixin.reopen({
     @method controllerFor
     @see {Ember.Route#controllerFor}
     @deprecated Use `needs` instead
+    @public
   */
   controllerFor(controllerName) {
     Ember.deprecate("Controller#controllerFor is deprecated, please use Controller#needs instead");
@@ -172,6 +177,7 @@ ControllerMixin.reopen({
     @see {Ember.ControllerMixin#needs}
     @property {Object} controllers
     @default null
+    @public
   */
   controllers: defaultControllersComputedProperty
 });

packages/ember-application/lib/main.js

@@ -2,11 +2,8 @@ import Ember from 'ember-metal/core';
 import { runLoadHooks } from 'ember-runtime/system/lazy_load';
 
 /**
-Ember Application
-
 @module ember
 @submodule ember-application
-@requires ember-views, ember-routing
 */
 
 import DefaultResolver from 'ember-application/system/resolver';

packages/ember-application/lib/system/application-instance.js

@@ -30,6 +30,8 @@ import Registry from 'container/registry';
   That state is what the `ApplicationInstance` manages: it is responsible for
   creating the container that contains all application state, and disposing of
   it once the particular test run or FastBoot request has finished.
+
+  @public
 */
 
 export default EmberObject.extend({
@@ -38,6 +40,7 @@ export default EmberObject.extend({
     instance-specific state for this application run.
 
     @property {Ember.Container} container
+    @public
   */
   container: null,
 
@@ -46,6 +49,7 @@ export default EmberObject.extend({
     and other code that makes up the application.
 
     @property {Ember.Registry} registry
+    @private
   */
   applicationRegistry: null,
 
@@ -54,6 +58,7 @@ export default EmberObject.extend({
     `applicationRegistry` as a fallback.
 
     @property {Ember.Registry} registry
+    @private
   */
   registry: null,
 
@@ -156,7 +161,9 @@ export default EmberObject.extend({
     this._didSetupRouter = true;
   },
 
-  /** @private
+  /**
+    @private
+
     Sets up the router, initializing the child router and configuring the
     location before routing begins.