[wp-trac] [WordPress Trac] #41682: JSDoc correction for namespaces

[WordPress Trac]

#41682: JSDoc correction for namespaces
--------------------------+-------------------------------
 Reporter:  herregroen    |       Owner:  adamsilverstein
     Type:  defect (bug)  |      Status:  assigned
 Priority:  normal        |   Milestone:  4.9
Component:  General       |     Version:
 Severity:  normal        |  Resolution:
 Keywords:  has-patch     |     Focuses:  javascript, docs
--------------------------+-------------------------------

Comment (by herregroen):

 @adamsilverstein

 * The third patch contains a single additional character on a line that's
 changed in both version ( `@class wp.media.collectio` -> `@class
 wp.media.collection` ).
 * The `@lends` statements need to be right before the object passed to
 extend starts. An alternative to reduce line lengths could be:

 {{{#!javascript
     Class.extend(
         /** @lends Class.prototype */
         {
             method: function () {
                 // Do stuff.
             }
             ...
 }}}

 * The comments I've removed were either incorrectly used `@global` tags (
 these do not document a global being used, they document that the
 function/variable being documented is a global and thus override
 `@memberOf` statements ) or comments I felt added no additional
 information when the correct tags were added ( for example: `utility
 function namespace` to `@namespace wp.customize.utils` )
 * The parse errors are expected. The `@global` tags I've removed were not
 the only tags being incorrectly used and JSDoc throws errors for each
 incorrect usage. The official WordPress javascript documentation standards
 ( https://make.wordpress.org/core/handbook/best-practices/inline-
 documentation-standards/javascript/ ) are not compatible with JSDoc and
 using them will result in errors. My suggestion here would be to change
 the javascript documentation standards to match the standards of JSDoc,
 but that's probably an issue for another ticket.

--
Ticket URL: <https://core.trac.wordpress.org/ticket/41682#comment:13>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform