Add comment blocks to classes/methods/properties

[teddyzeenny]

Part of #360

Use YUIDoc format to comment on all classes/methods/properties.

Classes, methods, and properties should have a detailed description above them about what they do and how they are used. If a method/property is clearly self descriptive, no description is needed.

Classes need the @namespace and @class keywords.
Methods need the @method method-name, @param {Type} name Description, @return {Type} Description keywords.
Properties need the @property property-name, @type {Type}, @default default-value.

Computed properties are @property (not @method).

Example:

// app/adapters/basic.js

const { Object: EmberObject } = Ember;

/**
 * This is the parent adapter to be extended by all other adapters. 
 * It provides an abstraction to keep the code browser/environment agnostic. 
 * Adapters are instantiated and injected into Ember objects automatically. 
 * Properties and methods in this parent class need to be overridden.
 * 
 * @namespace Adapters
 * @class Basic
 */
export default EmberObject.extend({

  /**
   * Inspect a specific DOM element. This usually means using
   * the current environment's tools to inspector the element in the DOM tree.
   *
   * For example, in Chrome, `inspect(elem)` will open the Elements tab in dev tools
   * and highlight the element.
   *
   * @method inspectElement
   * @param {DOM Element} elem
   */
  inspectElement function(/* elem */) {},

  /**
   * Indicates whether the current environment
   * supports opening up a specific file for debugging.
   * An example is opening up a resource in the Chrome
   * Devtools "Sources" panel.
   *
   * @property canOpenResource
   * @type {Boolean}
   * @default false
   */
  canOpenResource: false
});

[pete-the-pete]

@teddyzeenny I'd like to help with this, it would be a good way to get to know the code.

[locks]

@pete-the-pete are you still interested?

[pete-the-pete]

Yes, still interested, but obviously got busy and forgot about this. I
haven't worked on in since that PR. I can start contributing again next
week, but it someone else is ready to take it, I don't want to be in the
way.

On Thu, Sep 22, 2016 at 7:05 AM, Ricardo Mendes [email protected]
wrote:

@pete-the-pete https://github.com/pete-the-pete are you still
interested?

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
#378 (comment),
or mute the thread
https://github.com/notifications/unsubscribe-auth/AAVHgVxUClMZIlorv3Hdeju5WZ3mTtAXks5qsospgaJpZM4E2l4O
.

[locks]

@pete-the-pete no worries, this is in the "nice to have" camp so you're not blocking work. See you next week!

[ynotdraw]

I'd love to lend a hand here!

[RobbieTheWagner]

@ynotdraw please do! There is a lot of magic and complex code in Inspector, so the more docs the better!

[RobbieTheWagner]

@ynotdraw let's sync up on what you would like to work on here, and split this into more concrete and manageable chunks of work.