Add (JSDoc)umentation to the Backbone-centric Media files

[wonderboymusic]

See: ​http://make.wordpress.org/core/2014/01/13/audio-video-2-0-codename-disco-fries/

This is a spike ticket for feedback and commits about JSDoc implementation inside the @koop Media code from 3.5

[wonderboymusic]

26870-media-views.diff​ is a first pass at documenting src/wp-includes/js/media-views.js. It would be an understatement to say I almost blacked out several times chasing down all of the chains of inheritance. There is still more to document, but I think this could go in for a base to work from.

Notes:

• THE most important thing is the inheritance chain of each class with a constructor. Many of them inherit from classes 6 levels deep and mix-in wp.media.controller.StateMachine just for laughs. These classes are marked with @constructor, and the classes in the inheritance chain are annotated with @augments
• The next most important step for a lot of this code is documenting this inside of instance methods with the @this annotation. This is by far the most confusing aspect of a lot of the code.
• wp.media.controller.State is basically an abstract class that many of these classes are intertwined with.
• wp.media.controller.Region provides a lot of the black voodoo that triggers custom events

Anyways - more to be done.

[wonderboymusic]

26870-media-models.diff​ adds initial JSDoc blocks for src/wp-includes/js/media-models.js - this is a base to work from and iterate on

[wonderboymusic]

26870-media-editor.diff​​ add baseline docs to src/wp-includes/js/media-editor.js - will need more iterations, but this gets us started.

[wonderboymusic]

In 26984:

Add initial JSDoc blocks to media-editor.js. The initial blocks are a baseline to work from and invite future iterations. Initial commit is to avoid commits this large in the future.

See #26870.

[wonderboymusic]

In 26985:

Add initial JSDoc blocks to media-models.js. The initial blocks are a baseline to work from and invite future iterations. Initial commit is to avoid commits this large in the future.

See #26870.

[markoheijnen]

Was the first part of [26985] intended? Little bit clueless here. To me this is a code change and not documentation so I rather would have seen two commits to make it clear why it was done.

[wonderboymusic]

There are several places where it is hard to disambiguate / add inline docs, due to missing {}s around if/elses - no longer

[wonderboymusic]

In 26987:

Elaborate on JSDoc blocks for media-editor.js.

See #26870.

[wonderboymusic]

In 26988:

Correct a type.

See #26870.

[wonderboymusic]

In 26990:

Remove debug cruft.

Props nacin.
See #26870.

[wonderboymusic]

In 26991:

Make some @param types more specific in media-models.js.

See #26870.

[wonderboymusic]

In 27000:

Add the @namespace annotation where appropriate in media-editor.js. Also indicate the default value of a few params via the [options={}] syntax.

See #26870.

[wonderboymusic]

In 27005:

Add inline docs to each method of the namespaced objects in media-editor.js, explaining what each does. Add inline docs to params as well.

See #26870.

[wonderboymusic]

In 27031:

Add some JSDoc annotations to media-models.js to disambiguate instance properties and static class properties/methods in the base media Models.

See #26870.

[nacin]

Rock.

[wonderboymusic]

In 27032:

Add some inline docs to methods in media-models.js - particularly around @param and @returns.

See #26870.

[gcorne]

While doing a bit of jshint work on media-views.js, I noticed:

/**
  * call 'validator' directly on wp.media.model.Selection
  */
&& media.model.Selection.prototype.validator.apply( this, arguments );

@wonderboymusic, I am not sure it makes sense to document what is standard, albeit ugly, javascript. This particular case also breaks the jshint rules and makes the logical expression a bit harder to read, which is why it jumped out to me. If we feel like these statements are not clear, maybe we want to introduce a _super() method. I have seen but not used the following approach for doing this, which we probably would want to add only at the wp.Backbone or wp.media level.

Backbone.Model.prototype._super = function(funcName){
    return this.constructor.__super__[funcName].apply(this, _.rest(arguments));
};

[wonderboymusic]

yeahhh... some of that is overzealous - so much of that code was a black hole when I started, the extra comments were more for my own comfort than anything else. Feel free to make whatever edits you feel are necessary - I just wanted to get the ball rolling so I understood how all of it worked.

[gcorne]

26870-media-views-02.patch​ removes the comments when calling super via Function.prototype.apply and adds a bit of context to the documentation for some of the base constructors.

[wonderboymusic]

In 27126:

Add some inline docs to media-views.js and remove some unnecessary comments from a few super calls.

Props gcorne.
See #26870.

[kovshenin]

Typo in r26986, see 26870.diff​.

[wonderboymusic]

In 27309:

Correct a misspelled property name in a media-views.js annotation.

Props kovshenin.
See #26870.

[nacin]

Anything big left here?