by
583 9
0
2
191
0
Popular
Specified
Popularity: 1240368th place

Published on:

No tags for this snippet yet.
LanguageDiff
LicenseMIT_X11
SourceGitHub

Google JavaScript Style GuideのRev. 2.11:2.93 (svn r65:r112) のdiff http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml

Google JavaScript Style GuideのRev. 2.11:2.93 (svn r65:r112) のdiff http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml: 
google-javascriptguide.xml.diff
Copy Embed Code
<iframe id="embedFrame" style="width:600px; height:300px;"
src="https://www.snip2code.com/Embed/154614/Google-JavaScript-Style-Guide-Rev--2-11-?startLine=0"></iframe>
Click on the embed code to copy it into your clipboard Width Height
Leave empty to retrieve all the content Start End
Index: javascriptguide.xml =================================================================== --- javascriptguide.xml (リビジョン 65) +++ javascriptguide.xml (リビジョン 138) @@ -3,14 +3,14 @@ <GUIDE title="Google JavaScript Style Guide"> <p class="revision"> - Revision 2.11 + Revision 2.93 </p> <address> Aaron Whyte<br/> Bob Jervis<br/> Dan Pupius<br/> - Eric Arvidsson<br/> + Erik Arvidsson<br/> Fritz Schneider<br/> Robby Walker<br/> </address> @@ -44,11 +44,15 @@ + + </CATEGORY> </OVERVIEW> <CATEGORY title="JavaScript Language Rules"> + + <STYLEPOINT title="var"> <SUMMARY> Declarations with <code>var</code>: Always @@ -67,37 +71,105 @@ <STYLEPOINT title="Constants"> <SUMMARY> - &gt;Use <code>NAMES_LIKE_THIS</code> for constants. - Use <code>@const</code> where appropriate. - Never use the <code>const</code> keyword. + <ul> + <li>Use <code>NAMES_LIKE_THIS</code> for constant <em>values</em>.</li> + <li>Use <code>@const</code> to indicate a constant (non-overwritable) + <em>pointer</em> (a variable or property).</li> + <li>Never use the + <a href="https://developer.mozilla.org/en/JavaScript/Reference/Statements/const"> + <code>const</code> keyword</a> + as it's not supported in Internet Explorer.</li> + </ul> </SUMMARY> <BODY> <DECISION> - <p>For simple primitive value constants, the naming convention is - enough.</p> - <CODE_SNIPPET> - /** - * The number of seconds in a minute. - * @type {number} - */ - goog.example.SECONDS_IN_A_MINUTE = 60; - </CODE_SNIPPET> - <p>For non-primitives, use the <code>@const</code> annotation.</p> - <CODE_SNIPPET> - /** - * The number of seconds in each of the given units. - * @type {Object.&lt;number&gt;} - * @const - */ - goog.example.SECONDS_TABLE = { - minute: 60, - hour: 60 * 60 - day: 60 * 60 * 24 - } - </CODE_SNIPPET> - <p>This allows the compiler to enforce constant-ness.</p> - <p>As for the <code>const</code> keyword, Internet Explorer doesn't - parse it, so don't use it.</p> + <SUBSECTION title="Constant values"> + + <p>If a value is intended to be <em>constant</em> + and <em>immutable</em>, it should be given a name + in <code>CONSTANT_VALUE_CASE</code>. + <code>ALL_CAPS</code> additionally implies <code>@const</code> + (that the value is not overwritable). + </p> + + <p>Primitive types (<code>number</code>, <code>string</code>, + <code>boolean</code>) are constant values.</p> + + <p><code>Objects</code>' + immutability is more subjective — objects should be + considered immutable only if they do not demonstrate observable + state change. This is not enforced by the compiler.</p> + + + </SUBSECTION> + + <SUBSECTION title="Constant pointers (variables and properties)"> + <p>The <code>@const</code> annotation on a variable or property + implies that it is not overwritable. This is enforced by the + compiler at build time. This behavior is consistent with the + <a href="https://developer.mozilla.org/en/JavaScript/Reference/Statements/const"> + <code>const</code> keyword</a> (which we do not use due to the + lack of support in Internet Explorer).</p> + + <p>A <code>@const</code> annotation on a method additionally + implies that the method cannot not be overridden in subclasses. + </p> + + <p>A <code>@const</code> annotation on a constructor implies the + class cannot be subclassed (akin to <code>final</code> in Java). + </p> + + </SUBSECTION> + + <SUBSECTION title="Examples"> + + <p>Note that <code>@const</code> does not necessarily imply + <code>CONSTANT_VALUES_CASE</code>. + + However, <code>CONSTANT_VALUES_CASE</code> + <em>does</em> imply <code>@const</code>. + </p> + + <CODE_SNIPPET> + /** + * Request timeout in milliseconds. + * @type {number} + */ + goog.example.TIMEOUT_IN_MILLISECONDS = 60; + </CODE_SNIPPET> + + <p>The number of seconds in a minute never changes. It is a + constant value. <code>ALL_CAPS</code> + also implies <code>@const</code>, so the constant cannot be + overwritten. + </p> + + <p>The open source compiler will allow the symbol to be + overwritten because the constant is + <em>not</em> marked as <code>@const</code>.</p> + + <CODE_SNIPPET> + /** + * Map of URL to response string. + * @const + */ + MyClass.fetchedUrlCache_ = new goog.structs.Map(); + </CODE_SNIPPET> + + <CODE_SNIPPET> + /** + * Class that cannot be subclassed. + * @const + * @constructor + */ + sloth.MyFinalClass = function() {}; + </CODE_SNIPPET> + + <p>In this case, the pointer can never be overwritten, but + value is highly mutable and <b>not</b> constant (and thus in + <code>camelCase</code>, not <code>ALL_CAPS</code>).</p> + </SUBSECTION> + </DECISION> </BODY> </STYLEPOINT> @@ -129,7 +201,7 @@ // 2. Trying to do one thing on Internet Explorer and another on Firefox. // I know you'd never write code like this, but throw me a bone. - [normalVersion, ffVersion][isIE](); + [ffVersion, ieVersion][isIE](); var THINGS_TO_EAT = [apples, oysters, sprayOnCheese] // No semicolon here. @@ -144,23 +216,38 @@ "called" resulting in an error.</li> <li>You will most likely get a 'no such property in undefined' error at runtime as it tries to call - <code>x[ffVersion][isIE]()</code>.</li> - <li><code>die</code> is called unless - <code>resultOfOperation()</code> is <code>NaN</code> and - <code>THINGS_TO_EAT</code> gets assigned the result of - <code>die()</code>.</li> + <code>x[ffVersion, ieVersion][isIE]()</code>.</li> + <li><code>die</code> is always called since the array minus 1 is + <code>NaN</code> which is never equal to anything (not even if + <code>resultOfOperation()</code> returns <code>NaN</code>) and + <code>THINGS_TO_EAT</code> gets assigned the result of + <code>die()</code>.</li> </ol> </SUBSECTION> <SUBSECTION title="Why?"> - <p>JavaScript requires statements to end with a semicolon, - except when it thinks it can safely infer their existence. In each - of these examples, a function declaration or object or array literal - is used inside a statement. The closing brackets are not enough to - signal the end of the statement. Javascript never ends a statement - if the next token is an infix or bracket operator.</p> + <p>JavaScript requires statements to end with a semicolon, except when + it thinks it can safely infer their existence. In each of these + examples, a function declaration or object or array literal is used + inside a statement. The closing brackets are not enough to signal + the end of the statement. Javascript never ends a statement if the + next token is an infix or bracket operator.</p> <p>This has really surprised people, so make sure your assignments end with semicolons.</p> </SUBSECTION> + <SUBSECTION title="Clarification: Semicolons and functions"> + <p>Semicolons should be included at the end of function expressions, + but not at the end of function declarations. The distinction is + best illustrated with an example:</p> + <CODE_SNIPPET> + var foo = function() { + return true; + }; // semicolon here. + + function foo() { + return true; + } // no semicolon here. + </CODE_SNIPPET> + </SUBSECTION> </BODY> </STYLEPOINT> @@ -193,7 +280,7 @@ Expression to define a function within a block:</p> <CODE_SNIPPET> if (x) { - var foo = function() {} + var foo = function() {}; } </CODE_SNIPPET> </BODY> @@ -271,8 +358,7 @@ <a href="http://code.google.com/closure/library/"> the Closure Library </a> - or something similar. - + or a similar library function. </p> <CODE_SNIPPET> function D() { @@ -287,27 +373,68 @@ </BODY> </STYLEPOINT> - <STYLEPOINT title="Method definitions"> - <SUMMARY><code>Foo.prototype.bar = function() { ... };</code></SUMMARY> + <STYLEPOINT title="Method and property definitions"> + <SUMMARY><code>/** @constructor */ + function SomeConstructor() { + this.someProperty = 1; + } + Foo.prototype.someMethod = function() { ... };</code></SUMMARY> <BODY> - <p>While there are several methods for attaching methods and - properties to a constructor, the preferred style is:</p> + <p>While there are several ways to attach methods and properties to an + object created via "new", the preferred style for methods + is:</p> <CODE_SNIPPET> Foo.prototype.bar = function() { /* ... */ }; </CODE_SNIPPET> + <p>The preferred style for other properties is to initialize the field + in the constructor:</p> + <CODE_SNIPPET> + /** @constructor */ + function Foo() { + this.bar = value; + } + </CODE_SNIPPET> + <SUBSECTION title="Why?"> + <p>Current JavaScript engines optimize based on the "shape" + of an object, <a href="https://developers.google.com/v8/design#prop_access"> + adding a property to an object (including overriding + a value set on the prototype) changes the shape and can degrade + performance.</a></p> + </SUBSECTION> </BODY> </STYLEPOINT> + <STYLEPOINT title="delete"> + <SUMMARY>Prefer <code>this.foo = null</code>.</SUMMARY> + <BODY> + <CODE_SNIPPET> + Foo.prototype.dispose = function() { + this.property_ = null; + }; + </CODE_SNIPPET> + <p>Instead of:</p> + <BAD_CODE_SNIPPET> + Foo.prototype.dispose = function() { + delete this.property_; + }; + </BAD_CODE_SNIPPET> + <p>In modern JavaScript engines, changing the number of properties on an + object is much slower than reassigning the values. The delete keyword + should be avoided except when it is necessary to remove a property + from an object's iterated list of keys, or to change the result of + <code>if (key in obj)</code>.</p> + </BODY> + </STYLEPOINT> + <STYLEPOINT title="Closures"> <SUMMARY>Yes, but be careful.</SUMMARY> <BODY> <p>The ability to create closures is perhaps the most useful and often overlooked feature of JS. Here is <a href="http://jibbering.com/faq/faq_notes/closures.html"> - a good description of how closures work - </a>.</p> + a good description of how closures work</a>.</p> <p>One thing to keep in mind, however, is that a closure keeps a pointer to its enclosing scope. As a result, attaching a closure to a DOM element can create a circular reference and thus, a memory leak. For @@ -329,7 +456,7 @@ } function bar(a, b) { - return function() { /* uses a and b */ } + return function() { /* uses a and b */ }; } </CODE_SNIPPET> </BODY> @@ -337,53 +464,43 @@ <STYLEPOINT title="eval()"> <SUMMARY> - Only for deserialization (e.g. evaluating RPC responses) + Only for code loaders and REPL (Read–eval–print loop) </SUMMARY> <BODY> <p><code>eval()</code> makes for confusing semantics and is dangerous to use if the string being <code>eval()</code>'d contains user input. - There's usually a better, more clear, safer way to write your code, so - its used is generally not permitted. However <code>eval</code> makes - deserialization considerably easier than the non-<code>eval</code> - alternatives, so its use is acceptable for this task (for example, to - evaluate RPC responses).</p> - <p>Deserialization is the process of transforming a series of bytes into - an in-memory data structure. For example, you might write objects out - to a file as:</p> + There's usually a better, clearer, and safer way to write your code, + so its use is generally not permitted.</p> + + <p>For RPC you can always use JSON and read the result using + <code>JSON.parse()</code> instead of <code>eval()</code>.</p> + + <p>Let's assume we have a server that returns something like this:</p> + <CODE_SNIPPET> - users = [ - { - name: 'Eric', - id: 37824, - email: 'jellyvore@myway.com' - }, - { - name: 'xtof', - id: 31337, - email: 'b4d455h4x0r@google.com' - }, - ... - ]; + { + "name": "Alice", + "id": 31502, + "email": "looking_glass@example.com" + } </CODE_SNIPPET> - <p>Reading these data back into memory is as simple as - <code>eval</code>ing the string representation of the file.</p> - <p>Similarly, <code>eval()</code> can simplify decoding RPC return - values. For example, you might use an <code>XMLHttpRequest</code> - to make an RPC, and in its response the server can return - JavaScript:</p> + + <BAD_CODE_SNIPPET> + var userInfo = eval(feed); + var email = userInfo['email']; + </BAD_CODE_SNIPPET> + + <p>If the feed was modified to include malicious JavaScript code, then + if we use <code>eval</code> then that code will be executed.</p> + <CODE_SNIPPET> - var userOnline = false; - var user = 'nusrat'; - var xmlhttp = new XMLHttpRequest(); - xmlhttp.open('GET', 'http://chat.google.com/isUserOnline?user=' + user, false); - xmlhttp.send(''); - // Server returns: - // userOnline = true; - if (xmlhttp.status == 200) { - eval(xmlhttp.responseText); - } - // userOnline is now true. + var userInfo = JSON.parse(feed); + var email = userInfo['email']; </CODE_SNIPPET> + + <p>With <code>JSON.parse</code>, invalid JSON (including all executable + JavaScript) will cause an exception to be thrown.</p> + </BODY> </STYLEPOINT> @@ -504,6 +621,15 @@ at compile time; whitespace after the slash will result in tricky errors; and while most script engines support this, it is not part of ECMAScript. </p> + <p>Use string concatenation instead:</p> + <CODE_SNIPPET> + var myString = 'A rather long string of English text, an error message ' + + 'actually that just keeps going and going -- an error ' + + 'message to make the Energizer bunny blush (right through ' + + 'those Schwarzenegger shades)! Where was I? Oh yes, ' + + 'you\'ve got an error and all the extraneous whitespace is ' + + 'just gravy. Have a nice day.'; + </CODE_SNIPPET> </BODY> </STYLEPOINT> @@ -579,11 +705,11 @@ <SUMMARY>No</SUMMARY> <BODY> <p>Don't do this:</p> - <CODE_SNIPPET> + <BAD_CODE_SNIPPET> var f = function () { /*@cc_on if (@_jscript) { return 2* @*/ 3; /*@ } @*/ }; - </CODE_SNIPPET> + </BAD_CODE_SNIPPET> <p>Conditional Comments hinder automated tools as they can vary the JavaScript syntax tree at runtime.</p> </BODY> @@ -593,27 +719,35 @@ <CATEGORY title="JavaScript Style Rules"> <STYLEPOINT title="Naming"> <SUMMARY> - <p>In general, use <code>functionNamesLikeThis</code>, - <code>variableNamesLikeThis</code>, <code>ClassNamesLikeThis</code>, - <code>EnumNamesLikeThis</code>, <code>methodNamesLikeThis</code>, - and <code>SYMBOLIC_CONSTANTS_LIKE_THIS</code>.</p> - <p>Expand for more information.</p> + <p>In general, use + <code>functionNamesLikeThis</code>, + <code>variableNamesLikeThis</code>, + <code>ClassNamesLikeThis</code>, + <code>EnumNamesLikeThis</code>, + <code>methodNamesLikeThis</code>, + <code>CONSTANT_VALUES_LIKE_THIS</code>, + <code>foo.namespaceNamesLikeThis.bar</code>, and + <code>filenameslikethis.js</code>. + </p> </SUMMARY> <BODY> <SUBSECTION title="Properties and methods"> <ul> - <li><em>Private</em> properties, variables, and methods (in files - or classes) should be named with a trailing - underscore. + <li><em>Private</em> properties and methods should be named with a + trailing underscore. </li> - <li><em>Protected</em> properties, variables, and methods should be + <li><em>Protected</em> properties and methods should be named without a trailing underscore (like public ones).</li> </ul> <p>For more information on <em>private</em> and <em>protected</em>, read the section on <a href="#Visibility__private_and_protected_fields_"> - visibility - </a>.</p> + visibility</a>. + </p> + + + + </SUBSECTION> <SUBSECTION title="Method and function parameter"> @@ -629,13 +763,26 @@ </SUBSECTION> <SUBSECTION title="Getters and Setters"> - <p>Getters and setters for properties are not required. However, if - they are used, then getters must be named <code>getFoo()</code> and - setters must be named <code>setFoo(value)</code>. (For boolean - getters, <code>isFoo()</code> is also acceptable, and often sounds - more natural.)</p> + <p>EcmaScript 5 getters and setters for properties are discouraged. + However, if they are used, then getters must not change observable + state.</p> + <BAD_CODE_SNIPPET> + /** + * WRONG -- Do NOT do this. + */ + var foo = { get next() { return this.nextId++; } }; + </BAD_CODE_SNIPPET> </SUBSECTION> + <SUBSECTION title="Accessor functions"> + <p>Getters and setters methods for properties are not required. + However, if they are used, then getters must be named + <code>getFoo()</code> and setters must be named + <code>setFoo(value)</code>. (For boolean getters, + <code>isFoo()</code> is also acceptable, and often sounds more + natural.)</p> + </SUBSECTION> + <SUBSECTION title="Namespaces"> <p>JavaScript has no inherent packaging or namespacing support.</p> <p>Global name conflicts are difficult to debug, and can cause @@ -695,7 +842,7 @@ /** * WRONG -- Do NOT do this. * @constructor - * @extend {foo.hats.RoundHat} + * @extends {foo.hats.RoundHat} */ foo.hats.BowlerHat = function() { }; @@ -712,7 +859,7 @@ /** * @constructor - * @extend {foo.hats.RoundHat} + * @extends {foo.hats.RoundHat} */ googleyhats.BowlerHat = function() { ... @@ -747,7 +894,8 @@ staticHelper(new MyClass()); }; </CODE_SNIPPET> - <p>Do not alias namespaces.</p> + <p>Do not create local aliases of namespaces. Namespaces should only + be aliased using <a href="#goog-scope">goog.scope</a>.</p> <BAD_CODE_SNIPPET> myapp.main = function() { var namespace = some.long.namespace; @@ -830,7 +978,7 @@ </STYLEPOINT> <STYLEPOINT title="Code formatting"> - <SUMMARY>Expand for more info.</SUMMARY> + <SUMMARY>Expand for more information.</SUMMARY> <BODY> <p>We follow the <a href="cppguide.xml#Formatting">C++ formatting rules</a> in spirit, with the following additional clarifications.</p> @@ -854,7 +1002,7 @@ var obj = {a: 1, b: 2, c: 3}; // No space after { or before }. </CODE_SNIPPET> <p>Multiline array initializers and object initializers are indented - 2 spaces, just like blocks.</p> + 2 spaces, with the braces on their own line, just like blocks.</p> <CODE_SNIPPET> // Object initializer. var inset = { @@ -934,8 +1082,8 @@ // ... } - // Parenthesis-aligned, one argument per line. Visually groups and - // emphasizes each individual argument. + // Parenthesis-aligned, one argument per line. Emphasizes each + // individual argument. function bar(veryDescriptiveArgumentNumberOne, veryDescriptiveArgumentTwo, tableModelEventHandlerProxy, @@ -943,19 +1091,29 @@ // ... } </CODE_SNIPPET> + <p>When the function call is itself indented, you're free to start the + 4-space indent relative to the beginning of the original statement + or relative to the beginning of the current function call. + The following are all acceptable indentation styles.</p> + <CODE_SNIPPET> + if (veryLongFunctionNameA( + veryLongArgumentName) || + veryLongFunctionNameB( + veryLongArgumentName)) { + veryLongFunctionNameC(veryLongFunctionNameD( + veryLongFunctioNameE( + veryLongFunctionNameF))); + } + </CODE_SNIPPET> </SUBSECTION> <SUBSECTION title="Passing Anonymous Functions"> <p>When declaring an anonymous function in the list of arguments for a function call, the body of the function is indented two spaces - from the left edge of the function call or the statement, not two - spaces from the left edge of the function keyword. This is to make - the body of the anonymous function easier to read (i.e. not be all - squished up into the right half of the screen).</p> + from the left edge of the statement, or two spaces from the left + edge of the function keyword. This is to make the body of the + anonymous function easier to read (i.e. not be all squished up into + the right half of the screen).</p> <CODE_SNIPPET> - var names = items.map(function(item) { - return item.name; - }); - prefix.something.reallyLongFunctionName('whatever', function(a1, a2) { if (a1.equals(a2)) { someOtherLongFunctionName(a1); @@ -963,17 +1121,81 @@ andNowForSomethingCompletelyDifferent(a2.parrot); } }); + + var names = prefix.something.myExcellentMapFunction( + verboselyNamedCollectionOfItems, + function(item) { + return item.name; + }); </CODE_SNIPPET> </SUBSECTION> - <SUBSECTION title="More Indentation"> - <p>In fact, except for - <a href="#Array_and_Object_literals"> - array and object initializers - </a>, and passing anonymous functions, all wrapped lines - should be indented either left-aligned to the expression above, or - indented four spaces, not indented two spaces.</p> + <SUBSECTION title="Aliasing with goog.scope"> + <a name="goog-scope"/> + <p> + <a href="https://docs.google.com/document/pub?id=1ETFAuh2kaXMVL-vafUYhaWlhl6b5D9TOvboVg7Zl68Y"><code>goog.scope</code></a> + may be used to shorten references to + namespaced symbols in programs using + <a href="http://code.google.com/closure/library/">the Closure + Library</a>.</p> + <p>Only one <code>goog.scope</code> invocation may be added per + file. Always place it in the global scope.</p> + <p>The opening <code>goog.scope(function() {</code> invocation + must be preceded by exactly one blank line and follow any + <code>goog.provide</code> statements, <code>goog.require</code> + statements, or top-level comments. The invocation must be closed on + the last line in the file. Append <code>// goog.scope</code> to the + closing statement of the scope. Separate the comment from the + semicolon by two spaces.</p> + <p>Similar to C++ namespaces, do not indent under goog.scope + declarations. Instead, continue from the 0 column.</p> + <p>Only alias names that will not be re-assigned to another object + (e.g., most constructors, enums, and namespaces). Do not do + this (see below for how to alias a constructor):</p> + <BAD_CODE_SNIPPET> + goog.scope(function() { + var Button = goog.ui.Button; + + Button = function() { ... }; + ... + </BAD_CODE_SNIPPET> + + <p>Names must be the same as the last property of the global that they + are aliasing.</p> + <CODE_SNIPPET> + goog.provide('my.module.SomeType'); + + goog.require('goog.dom'); + goog.require('goog.ui.Button'); + + goog.scope(function() { + var Button = goog.ui.Button; + var dom = goog.dom; + + // Alias new types <b>after</b> the constructor declaration. + my.module.SomeType = function() { ... }; + var SomeType = my.module.SomeType; + + // Declare methods on the prototype as usual: + SomeType.prototype.findButton = function() { + // Button as aliased above. + this.button = new Button(dom.getElement('my-button')); + }; + ... + }); // goog.scope + </CODE_SNIPPET> + </SUBSECTION> + <SUBSECTION title="Indenting wrapped lines"> + <p>Except for <a href="#Array_and_Object_literals">array literals, + object literals</a>, and anonymous functions, all wrapped lines + should be indented either left-aligned to a sibling expression + above, or four spaces (not two spaces) deeper than a parent + expression (where "sibling" and "parent" refer to parenthesis + nesting level). + </p> + + <CODE_SNIPPET> someWonderfulHtml = '<div class="' + getClassesForWonderfulHtml()'">' + getEvenMoreHtml(someReallyInterestingValues, moreValues, evenMoreParams, 'a duck', true, 72, @@ -983,9 +1205,14 @@ thisIsAVeryLongVariableName = hereIsAnEvenLongerOtherFunctionNameThatWillNotFitOnPrevLine(); - thisIsAVeryLongVariableName = 'expressionPartOne' + someMethodThatIsLong() + - thisIsAnEvenLongerOtherFunctionNameThatCannotBeIndentedMore(); + thisIsAVeryLongVariableName = siblingOne + siblingTwo + siblingThree + + siblingFour + siblingFive + siblingSix + siblingSeven + + moreSiblingExpressions + allAtTheSameIndentationLevel; + thisIsAVeryLongVariableName = operandOne + operandTwo + operandThree + + operandFour + operandFive * ( + aNestedChildExpression + shouldBeIndentedMore); + someValue = this.foo( shortArg, 'Some really long string arg - this is a pretty common case, actually.', @@ -1013,10 +1240,12 @@ </CODE_SNIPPET> </SUBSECTION> <SUBSECTION title="Binary and Ternary Operators"> - <p>Always put the operator on the preceding line, so that you don't - have to think about implicit semi-colon insertion issues. Otherwise, + <p>Always put the operator on the preceding line. Otherwise, line breaks and indentation follow the same rules as in other - Google style guides.</p> + Google style guides. This operator placement was initially agreed + upon out of concerns about automatic semicolon insertion. In fact, + semicolon insertion cannot happen before a binary operator, but new + code should stick to this style for consistency.</p> <CODE_SNIPPET> var x = a ? b : c; // All on one line if it will fit. @@ -1029,6 +1258,12 @@ moreComplicatedB : moreComplicatedC; </CODE_SNIPPET> + <p>This includes the dot operator.</p> + <CODE_SNIPPET> + var x = foo.bar(). + doSomething(). + doSomethingElse(); + </CODE_SNIPPET> </SUBSECTION> </BODY> </STYLEPOINT> @@ -1041,7 +1276,8 @@ <p>Never use parentheses for unary operators such as <code>delete</code>, <code>typeof</code> and <code>void</code> or after keywords such as <code>return</code>, <code>throw</code> as - well as others (<code>case</code>, in or <code>new</code>).</p> + well as others (<code>case</code>, <code>in</code> or + <code>new</code>).</p> </BODY> </STYLEPOINT> @@ -1063,7 +1299,12 @@ <p>We recommend the use of the JSDoc annotations <code>@private</code> and <code>@protected</code> to indicate visibility levels for classes, functions, and properties.</p> - + <p>The --jscomp_warning=visibility compiler flag turns on compiler + warnings for visibility violations. See + <a href="http://code.google.com/p/closure-compiler/wiki/Warnings"> + Closure Compiler + Warnings</a>. + </p> <p><code>@private</code> global variables and functions are only accessible to code in the same file.</p> <p>Constructors marked <code>@private</code> may only be instantiated by @@ -1102,26 +1343,31 @@ <p>Note that these semantics differ from those of C++ and Java, in that they grant private and protected access to all code in the same file, not just in the same class or class hierarchy. Also, unlike in C++, - private properties cannot be overriden by a subclass. + private properties cannot be overridden by a subclass. </p> <CODE_SNIPPET> // File 1. /** @constructor */ - AA_PublicClass = function() { + AA_PublicClass = function() { + /** @private */ + this.privateProp_ = 2; + + /** @protected */ + this.protectedProp = 4; }; /** @private */ AA_PublicClass.staticPrivateProp_ = 1; - /** @private */ - AA_PublicClass.prototype.privateProp_ = 2; - /** @protected */ AA_PublicClass.staticProtectedProp = 31; + /** @private */ + AA_PublicClass.prototype.privateMethod_ = function() {}; + /** @protected */ - AA_PublicClass.prototype.protectedProp = 4; + AA_PublicClass.prototype.protectedMethod = function() {}; // File 2. @@ -1153,31 +1399,37 @@ return this.protectedProp; }; </CODE_SNIPPET> + + <p>Notice that in JavaScript, there is no distinction between a type + (like <code>AA_PrivateClass_</code>) and the constructor for that + type. There is no way to express both that a type is public and its + constructor is private (because the constructor could easily be aliased + in a way that would defeat the privacy check).</p> </BODY> </STYLEPOINT> <STYLEPOINT title="JavaScript Types"> <SUMMARY>Encouraged and enforced by the compiler.</SUMMARY> <BODY> + <a name="JsTypes"/> <p>When documenting a type in JSDoc, be as specific and accurate as - possible. The types we support are + possible. The types we support are based on the <a href="http://wiki.ecmascript.org/doku.php?id=spec:spec"> - JS2 - </a> - style types and JS1.x types.</p> + EcmaScript 4 spec</a>.</p> <SUBSECTION title="The JavaScript Type Language"> - <p>The JS2 proposal contained a language for specifying JavaScript + <p>The ES4 proposal contained a language for specifying JavaScript types. We use this language in JsDoc to express the types of function parameters and return values.</p> - <p>As the JS2 proposal has evolved, this language has changed. The + <p>As the ES4 proposal has evolved, this language has changed. The compiler still supports old syntaxes for types, but those syntaxes are deprecated.</p> + <p/> <table border="1" style="border-collapse:collapse" cellpadding="4"> <thead> <tr> - <th>Operator Name</th> + <th>Syntax Name</th> <th>Syntax</th> <th>Description</th> <th>Deprecated Syntaxes</th> @@ -1185,16 +1437,64 @@ </thead> <tbody> <tr> - <td>Type Name</td> + <td>Primitive Type</td> <td> - <code>{boolean}</code>, <code>{Window}</code>, - <code>{goog.ui.Menu}</code> + There are 5 primitive types in JavaScript: + <code>{null}</code>, + <code>{undefined}</code>, + <code>{boolean}</code>, + <code>{number}</code>, and + <code>{string}</code>. </td> <td>Simply the name of a type.</td> <td/> </tr> <tr> + <td>Instance Type</td> + <td> + <code>{Object}</code><br/> + An instance of Object or null.<p/> + <code>{Function}</code><br/> + An instance of Function or null.<p/> + <code>{EventTarget}</code><br/> + An instance of a constructor that implements the EventTarget + interface, or null. + </td> + <td>An instance of a constructor or interface function.<p/> + + Constructor functions are functions defined with the + <code>@constructor</code> JSDoc tag. + Interface functions are functions defined with the + <code>@interface</code> JSDoc tag.<p/> + + By default, instance types will accept null. This is the only + type syntax that makes the type nullable. Other type syntaxes + in this table will not accept null. + </td> + <td/> + </tr> + + <tr> + <td>Enum Type</td> + <td> + <code>{goog.events.EventType}</code><br/> + One of the properties of the object literal initializer + of <code>goog.events.EventType</code>. + </td> + <td>An enum must be initialized as an object literal, or as + an alias of another enum, annotated with the <code>@enum</code> + JSDoc tag. The properties of this literal are the instances + of the enum. The syntax of the enum is defined + <a href="#enums">below</a>.<p/> + + Note that this is one of the few things in our type system + that were not in the ES4 spec. + </td> + <td/> + </tr> + + <tr> <td>Type Application</td> <td> <code>{Array.&lt;string&gt;}</code><br/>An array of strings.<p/> @@ -1202,7 +1502,7 @@ <br/>An object in which the keys are strings and the values are numbers. </td> - <td>Patameterizes a type, by applying a set of type arguments + <td>Parameterizes a type, by applying a set of type arguments to that type. The idea is analogous to generics in Java. </td> <td/> @@ -1213,41 +1513,27 @@ <td> <code>{(number|boolean)}</code><br/>A number or a boolean. </td> - <td>Indicates that a value might have type A OR type B.</td> - <td> - <code>{(number,boolean)}</code>, - <code>{number|boolean}</code>, - <code>{(number||boolean)}</code> - </td> - </tr> + <td>Indicates that a value might have type A OR type B.<p/> - <tr> - <td>Record Type</td> - <td> - <code>{{myNum: number, myObject}}</code> - <br/>An anonymous type with the given type members. + The parentheses may be omitted at the top-level + expression, but the parentheses should be included in + sub-expressions to avoid ambiguity.<br/> + <code>{number|boolean}</code><br/> + <code>{function(): (number|boolean)}</code> </td> <td> - <p>Indicates that the value has the specified members with the - specified types. In this case, <code>myNum</code> with a - type <code>number</code> and <code>myObject</code> with any - type.</p> - <p>Notice that the braces are part of the type syntax. For - example, to denote an <code>Array</code> of objects that - have a <code>length</code> property, you might write - <code>Array.&lt;{length}&gt;</code>.</p> + <code>{(number,boolean)}</code>,<br/> + <code>{(number||boolean)}</code> </td> - <td/> </tr> <tr> <td>Nullable type</td> <td> - <code>{?number}</code><br/> A number or NULL. + <code>{?number}</code><br/> A number or null. </td> - <td>Indicates that a value is type A or <code>null</code>. - By default, all object types are nullable. - NOTE: Function types are not nullable. + <td>Shorthand for the union of the null type with any + other type. This is just syntactic sugar. </td> <td> <code>{number?}</code> @@ -1260,9 +1546,8 @@ <code>{!Object}</code><br/> An Object, but never the <code>null</code> value. </td> - <td>Indicates that a value is type A and not null. By default, - all value types (boolean, number, string, and undefined) are - not nullable. + <td>Filters null out of nullable types. Most often used + with instance types, which are nullable by default. </td> <td> <code>{Object!}</code> @@ -1270,6 +1555,25 @@ </tr> <tr> + <td>Record Type</td> + <td> + <code>{{myNum: number, myObject}}</code> + <br/>An anonymous type with the given type members. + </td> + <td> + <p>Indicates that the value has the specified members with the + specified types. In this case, <code>myNum</code> with a + type <code>number</code> and <code>myObject</code> with any + type.</p> + <p>Notice that the braces are part of the type syntax. For + example, to denote an <code>Array</code> of objects that + have a <code>length</code> property, you might write + <code>Array.&lt;{length}&gt;</code>.</p> + </td> + <td/> + </tr> + + <tr> <td>Function Type</td> <td> <code>{function(string, boolean)}</code><br/> @@ -1302,6 +1606,18 @@ </tr> <tr> + <td>Function <code>new</code> Type</td> + <td> + <code>{function(new:goog.ui.Menu, string)}</code><br/> + A constructor that takes one argument (a string), and + creates a new instance of goog.ui.Menu when called + with the 'new' keyword. + </td> + <td>Specifies the constructed type of a constructor.</td> + <td/> + </tr> + + <tr> <td>Variable arguments</td> <td> <code>{function(string, ...[number]): number}</code><br/> @@ -1329,7 +1645,7 @@ </tr> <tr> - <td>Function <a href="optional">optional arguments</a></td> + <td>Function <a href="#optional">optional arguments</a></td> <td> <code>{function(?string=, number=)}</code><br/> A function that takes one optional, nullable string and one @@ -1343,7 +1659,7 @@ <tr> <td> <a name="optional-arg-annotation"/> - Function <a href="optional">optional arguments</a> + Function <a href="#optional">optional arguments</a> (in <code>@param</code> annotations) </td> <td> @@ -1361,6 +1677,14 @@ <td>Indicates that the variable can take on any type.</td> <td/> </tr> + + <tr> + <td>The UNKNOWN type</td> + <td><code>{?}</code></td> + <td>Indicates that the variable can take on any type, + and the compiler should not type-check any uses of it.</td> + <td/> + </tr> </tbody> </table> </SUBSECTION> @@ -1586,12 +1910,12 @@ </CODE_SNIPPET> </td> <td> - An Object in which the keys are numbers and the values - are strings. <p/>Note that in JavaScript, the keys are always - implicitly coverted to strings, so + An Object in which the keys are numbers and the values are + strings. <p/>Note that in JavaScript, the keys are always + implicitly converted to strings, so <code>obj['1'] == obj[1]</code>. - So the key wil always be a string in for...in loops. But the - compiler will verify the type if the key when indexing into + So the key will always be a string in for...in loops. But the + compiler will verify the type of the key when indexing into the object. </td> </tr> @@ -1625,7 +1949,7 @@ </tr> <tr> - <td>SomeClass</td> + <td><a name="constructor-tag">SomeClass</a></td> <td> <CODE_SNIPPET> /** @constructor */ @@ -1669,12 +1993,16 @@ <CODE_SNIPPET> /** @enum {string} */ project.MyEnum = { + /** The color blue. */ BLUE: '#0000dd', + /** The color red. */ RED: '#dd0000' }; </CODE_SNIPPET> </td> - <td><a href="#enums">Enumeration</a></td> + <td><a name="enums">Enumeration</a><p/> + JSDoc comments on enum values are optional. + </td> </tr> <tr> @@ -1710,6 +2038,17 @@ </table> </SUBSECTION> + <SUBSECTION title="Type Casts"> + <p>In cases where type-checking doesn't accurately infer the type of + an expression, it is possible to add a type cast comment by adding a + type annotation comment and enclosing the expression in + parentheses. The parentheses are required.</p> + + <CODE_SNIPPET> + /** @type {number} */ (x) + </CODE_SNIPPET> + </SUBSECTION> + <SUBSECTION title="Nullable vs. Optional Parameters and Properties"> <a name="optional"/> <p>Because JavaScript is a loosely-typed language, it is very @@ -1717,10 +2056,8 @@ nullable, and undefined function parameters and class properties.</p> - <p>Object types (also known as reference types) are nullable by - default. NOTE: Function types are not nullable by default. An - object is defined as anything except a string, number, boolean, - undefined, or null. For example, the following declaration</p> + <p>Instances of classes and interfaces are nullable by default. + For example, the following declaration</p> <CODE_SNIPPET> /** @@ -1812,162 +2149,109 @@ }; </CODE_SNIPPET> </SUBSECTION> - </BODY> - </STYLEPOINT> - <STYLEPOINT title="Comments"> - <SUMMARY>Use JSDoc</SUMMARY> - <BODY> - <p>We use - <a href="http://code.google.com/p/jsdoc-toolkit/"> - JSDoc - </a> - comments to document files, classes, methods and properties. Inline - comments should be of the // variety. Additionally, we follow the - <a href="cppguide.xml#Comments"> - C++ style for comments - </a> in spirit. This means you should have: - </p> - <ul> - <li>copyright and authorship notice,</li> - <li>a top-level (file-level) comment designed to orient readers - unfamiliar with the code to what's in this file (e.g., a - one-paragraph summary of what the major pieces are, how they fit - together, and with what they interact),</li> - <li>class, function, variable, and implementation comments as - necessary,</li> - <li>an indication of the browsers in which the code is expected to - work (if applicable), and</li> - <li>proper capitalization, punctuation, and spelling.</li> - </ul> + <SUBSECTION title="Typedefs"> + <a name="Typedefs"/> + <p>Sometimes types can get complicated. A function that accepts + content for an Element might look like:</p> - <p>Avoid sentence fragments. Start sentences with a properly - capitalized word, and end them with punctuation.</p> - - <p>Pretend there's some novice programmer that's going to come along and - have to maintain the code after you. There very well just might - be!</p> - - <p>There are now many compiler passes that extract type information from - JSDoc, in order to provide better code validation, removal, and - compression. It is, therefore, very important that you use full and - correct JSDoc.</p> - - <SUBSECTION title="Top/File-Level Comments"> - <p> - - The top level comment is designed - to orient readers unfamiliar with the code to what is in this file. - It should provide a description of the file's contents, its - author(s), and any dependencies or compatibility information. As an - example:</p> - <CODE_SNIPPET> - // Copyright 2009 Google Inc. All Rights Reserved. - /** - * @fileoverview Description of file, its uses and information - * about its dependencies. - * @author user@google.com (Firstname Lastname) + * @param {string} tagName + * @param {(string|Element|Text|Array.&lt;Element&gt;|Array.&lt;Text&gt;)} contents + * @return {!Element} */ + goog.createElement = function(tagName, contents) { + ... + }; </CODE_SNIPPET> - - </SUBSECTION> + <p>You can define commonly used type expressions with a + <code>@typedef</code> tag. For example,</p> - <SUBSECTION title="Class Comments"> - <p>Classes must be documented with a description and usage. - The constructor parameters must also be documented. - If the class inherits from another class, - that should be documented with an <code>@extends</code> tag. - If the class implements an interface, - that should be documented with an <code>@implements</code> tag. - </p> + <CODE_SNIPPET> + /** @typedef {(string|Element|Text|Array.&lt;Element&gt;|Array.&lt;Text&gt;)} */ + goog.ElementContent; - <CODE_SNIPPET> /** - * Class making something fun and easy. - * @param {string} arg1 An argument that makes this more interesting. - * @param {Array.&lt;number&gt;} arg2 List of numbers to be processed. - * @constructor - * @extends {goog.Disposable} + * @param {string} tagName + * @param {goog.ElementContent} contents + * @return {!Element} */ - project.MyClass = function(arg1, arg2) { - // ... + goog.createElement = function(tagName, contents) { + ... }; - goog.inherits(project.MyClass, goog.Disposable); </CODE_SNIPPET> </SUBSECTION> - <SUBSECTION title="Method and Function Comments"> - <p>A description must be provided along with parameters. Use full - sentences. Method descriptions should start with a sentence written - in the third person declarative voice.</p> + <SUBSECTION title="Template types"> + <a name="Template_types"/> + <p>The compiler has limited support for template types. It can only + infer the type of <code>this</code> inside an anonymous function + literal from the type of the <code>this</code> argument and whether the + <code>this</code> argument is missing.</p> <CODE_SNIPPET> /** - * Converts text to some completely different text. - * @param {string} arg1 An argument that makes this more interesting. - * @return {string} Some return value. + * @param {function(this:T, ...)} fn + * @param {T} thisObj + * @param {...*} var_args + * @template T */ - project.MyClass.prototype.someMethod = function(arg1) { - // ... + goog.bind = function(fn, thisObj, var_args) { + ... }; - - /** - * Operates on an instance of MyClass and returns something. - * @param {project.MyClass} obj Instance of MyClass which leads to a long - * comment that needs to be wrapped to two lines. - * @return {boolean} Whether something occured. - */ - function PR_someMethod(obj) { - // ... - } + // Possibly generates a missing property warning. + goog.bind(function() { this.someProperty; }, new SomeClass()); + // Generates an undefined this warning. + goog.bind(function() { this.someProperty; }); </CODE_SNIPPET> + </SUBSECTION> + </BODY> + </STYLEPOINT> - <p>For simple getters that take no parameters, the description can be - omitted.</p> + <STYLEPOINT title="Comments"> + <SUMMARY>Use JSDoc</SUMMARY> + <BODY> + <p> + We follow the + <a href="cppguide.xml#Comments"> + C++ style for comments</a> in spirit. + </p> - <CODE_SNIPPET> - /** - * @return {Element} The element for the component. - */ - goog.ui.Component.prototype.getElement = function() { - return this.element_; - }; - </CODE_SNIPPET> - </SUBSECTION> + <p>All files, classes, methods and properties should be documented with + <a href="http://code.google.com/p/jsdoc-toolkit/">JSDoc</a> + comments with the appropriate <a href="#JSDoc_Tag_Reference">tags</a> + and <a href="#JsTypes">types</a>. Textual descriptions for properties, + methods, method parameters and method return values should be included + unless obvious from the property, method, or parameter name. + </p> - <SUBSECTION title="Property Comments"> - <p>It is also nice to have comments for properties.</p> + <p>Inline comments should be of the <code>//</code> variety.</p> - <CODE_SNIPPET> - /** - * Maximum number of things per pane. - * @type {number} - */ - project.MyClass.prototype.someProperty = 4; - </CODE_SNIPPET> - </SUBSECTION> + <p>Complete sentences are recommended but not required. + Complete sentences should use appropriate capitalization + and punctuation.</p> - <SUBSECTION title="Type Cast Comments"> - <p>In cases where type-checking doesn't accurately infer the type of - an expression, it is possible to add a type cast comment by adding a - type annotation comment and enclosing the expression in - parenthesis. The parentheses are required, and may surround the type - annotation comment as well.</p> + <SUBSECTION title="Comment Syntax"> + <p>The JSDoc syntax is based on + <a href="http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html"> + JavaDoc</a>. Many tools extract metadata from JSDoc comments to + perform code validation and optimizations. These comments must be + well-formed.</p> <CODE_SNIPPET> - /** @type {number} */ (x) - (/** @type {number} */ x) + /** + * A JSDoc comment should begin with a slash and 2 asterisks. + * Inline tags should be enclosed in braces like {@code this}. + * @desc Block tags should always start on their own line. + */ </CODE_SNIPPET> </SUBSECTION> <SUBSECTION title="JSDoc Indentation"> - <p>If you have to line break a <code>@param</code>, - <code>@return</code>, <code>@supported</code>, <code>@this</code> or - <code>@deprecated</code> you should treat this as breaking a code - statement and indent it four spaces.</p> + <p>If you have to line break a block tag, you should treat this as + breaking a code statement and indent it four spaces.</p> <CODE_SNIPPET> /** @@ -1982,12 +2266,11 @@ }; </CODE_SNIPPET> - <p>You should not indent the <code>@fileoverview</code> command.</p> + <p>You should not indent the <code>@fileoverview</code> command. You do not have to + indent the <code>@desc</code> command.</p> <p>Even though it is not preferred, it is also acceptable to line up - the description. This has the side effect that you will have to - realign the text every time you change a variable name so this will - soon get your code out of sync.</p> + the description.</p> <CODE_SNIPPET> /** @@ -2003,269 +2286,412 @@ </CODE_SNIPPET> </SUBSECTION> - <SUBSECTION title="Enums"> - <a name="enums"/> + <SUBSECTION title="HTML in JSDoc"> + <p>Like JavaDoc, JSDoc supports many HTML tags, like &lt;code&gt;, + &lt;pre&gt;, &lt;tt&gt;, &lt;strong&gt;, &lt;ul&gt;, &lt;ol&gt;, + &lt;li&gt;, &lt;a&gt;, and others.</p> + + <p>This means that plaintext formatting is not respected. So, don't + rely on whitespace to format JSDoc:</p> + + <BAD_CODE_SNIPPET> + /** + * Computes weight based on three factors: + * items sent + * items received + * last timestamp + */ + </BAD_CODE_SNIPPET> + + <p>It'll come out like this:</p> + + <BAD_CODE_SNIPPET> + Computes weight based on three factors: items sent items received last timestamp + </BAD_CODE_SNIPPET> + + <p>Instead, do this:</p> + <CODE_SNIPPET> /** - * Enum for tri-state values. - * @enum {number} + * Computes weight based on three factors: + * &lt;ul&gt; + * &lt;li&gt;items sent + * &lt;li&gt;items received + * &lt;li&gt;last timestamp + * &lt;/ul&gt; */ - project.TriState = { - TRUE: 1, - FALSE: -1, - MAYBE: 0 - }; </CODE_SNIPPET> - <p>Note that enums are also valid <a href="#JavaScript_Types">types</a> - and thus can be used as parameter types, etc.</p> + The <a href="http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html"> + JavaDoc</a> style guide is a useful resource on how to write + well-formed doc comments. + </SUBSECTION> + <SUBSECTION title="Top/File-Level Comments"> + <p> + + A <a href="copyright.html">copyright notice</a> and author information are optional. + File overviews are generally recommended whenever a file consists of + more than a single class definition. The top level comment is + designed to orient readers unfamiliar with the code to what is in + this file. If present, it should provide a description of the + file's contents and any dependencies or compatibility information. + As an example: + </p> + <CODE_SNIPPET> /** - * Sets project state. - * @param {project.TriState} state New project state. + * @fileoverview Description of file, its uses and information + * about its dependencies. */ - project.setState = function(state) { - // ... - }; </CODE_SNIPPET> + + </SUBSECTION> - <SUBSECTION title="Typedefs"> - <p>Sometimes types can get complicated. A function that accepts - content for an Element might look like:</p> + <SUBSECTION title="Class Comments"> + <p>Classes must be documented with a description and a + <a href="#constructor-tag">type tag that + identifies the constructor</a>. + </p> <CODE_SNIPPET> /** - * @param {string} tagName - * @param {(string|Element|Text|Array.&lt;Element&gt;|Array.&lt;Text&gt;)} contents - * @return {Element} + * Class making something fun and easy. + * @param {string} arg1 An argument that makes this more interesting. + * @param {Array.&lt;number&gt;} arg2 List of numbers to be processed. + * @constructor + * @extends {goog.Disposable} */ - goog.createElement = function(tagName, contents) { - ... + project.MyClass = function(arg1, arg2) { + // ... }; + goog.inherits(project.MyClass, goog.Disposable); </CODE_SNIPPET> + </SUBSECTION> - <p>You can define commonly used type expressions with a - <code>@typedef</code> tag. For example,</p> - + <SUBSECTION title="Method and Function Comments"> + <p>Parameter and return types should be documented. The method + description may be omitted if it is obvious from the parameter + or return type descriptions. Method descriptions should start + with a sentence written in the third person declarative voice.</p> <CODE_SNIPPET> - /** @typedef {(string|Element|Text|Array.&lt;Element&gt;|Array.&lt;Text&gt;)} */ - goog.ElementContent; - /** - * @param {string} tagName - * @param {goog.ElementContent} contents - * @return {Element} - */ - goog.createElement = function(tagName, contents) { - ... - }; + * Operates on an instance of MyClass and returns something. + * @param {project.MyClass} obj Instance of MyClass which leads to a long + * comment that needs to be wrapped to two lines. + * @return {boolean} Whether something occurred. + */ + function PR_someMethod(obj) { + // ... + } </CODE_SNIPPET> </SUBSECTION> - + <SUBSECTION title="Property Comments"> + <CODE_SNIPPET> + /** @constructor */ + project.MyClass = function() { + /** + * Maximum number of things per pane. + * @type {number} + */ + this.someProperty = 4; + } + </CODE_SNIPPET> + </SUBSECTION> <SUBSECTION title="JSDoc Tag Reference"> + <a name="JSDoc_Tag_Reference"/> + <p/> <table border="1" style="border-collapse:collapse" cellpadding="4"> <thead> <tr> <th>Tag</th> <th>Template &amp; Examples</th> <th>Description</th> - <th>Type-Checking Support</th> </tr> </thead> <tbody> <tr> - <td><a name="tag-param">@param</a></td> <td> - <tt>@param {Type} varname Description</tt> + <a name="tag-author">@author</a> + + </td> + <td> + <code>@author username@google.com (first last)</code> <p><i>For example:</i></p> <CODE_SNIPPET> /** - * Queries a Baz for items. - * @param {number} groupNum Subgroup id to query. - * @param {string|number|null} term An itemName, - * or itemId, or null to search everything. + * @fileoverview Utilities for handling textareas. + * @author kuth@google.com (Uthur Pendragon) */ - goog.Baz.prototype.query = function(groupNum, term) { - // ... - }; </CODE_SNIPPET> </td> <td> - Used with method, function and constructor calls to document - the arguments of a function. + Document the author of a file or the owner of a test, + generally only used in the <code>@fileoverview</code> comment. + </td> - <td>Fully supported.</td> </tr> + + <tr> - <td><a name="tag-return">@return</a></td> + <td><a name="tag-code">@code</a></td> <td> - <tt>@return {Type} Description</tt> + <code>{@code ...}</code> <p><i>For example:</i></p> <CODE_SNIPPET> /** - * @return {string} The hex ID of the last item. + * Moves to the next position in the selection. + * Throws {@code goog.iter.StopIteration} when it + * passes the end of the range. + * @return {Node} The node at the next position. */ - goog.Baz.prototype.getLastId = function() { + goog.dom.RangeIterator.prototype.next = function() { // ... - return id; }; </CODE_SNIPPET> </td> <td> - Used with method and function calls to document the return - type. When writing descriptions for boolean parameters, - prefer "Whether the component is visible" to "True if the - component is visible, false otherwise". If there is no return - value, do not use an <code>@return</code> tag. + Indicates that a term in a JSDoc description is code so it may + be correctly formatted in generated documentation. </td> - <td>Fully supported.</td> </tr> <tr> + <td><a name="tag-const">@const</a></td> <td> - <a name="tag-author">@author</a> - + <code>@const</code><br/> + <code>@const {type}</code> + <p><i>For example:</i></p> + <CODE_SNIPPET> + /** @const */ var MY_BEER = 'stout'; + + /** + * My namespace's favorite kind of beer. + * @const {string} + */ + mynamespace.MY_BEER = 'stout'; + + /** @const */ MyClass.MY_BEER = 'stout'; + + /** + * Initializes the request. + * @const + */ + mynamespace.Request.prototype.initialize = function() { + // This method cannot be overridden in a subclass. + }; + </CODE_SNIPPET> </td> <td> - <tt>@author username@google.com (first last)</tt> + <p>Marks a variable (or property) as read-only and suitable + for inlining.</p> + + <p>A <code>@const</code> variable is an immutable pointer to + a value. If a variable or property marked as + <code>@const</code> is overwritten, JSCompiler will give + warnings.</p> + + <p>The type declaration of a constant value can be omitted + if it can be clearly inferred. An additional comment about + the variable is optional.</p> + + <p>When <code>@const</code> is applied to a method, it + implies the method is not only not overwritable, but also + that the method is <em>finalized</em> — + not overridable in subclasses.</p> + + <p>For more on <code>@const</code>, see the + <a href="#Constants">Constants</a> section.</p> + + </td> + </tr> + + <tr> + <td><a name="tag-constructor">@constructor</a></td> + <td> + <code>@constructor</code> <p><i>For example:</i></p> <CODE_SNIPPET> /** - * @fileoverview Utilities for handling textareas. - * @author kuth@google.com (Uthur Pendragon) + * A rectangle. + * @constructor */ + function GM_Rect() { + ... + } </CODE_SNIPPET> </td> <td> - Document the author of a file or the owner of a test, - generally only used in the <code>@fileoverview</code> comment. - + Used in a class's documentation to indicate the constructor. </td> - <td>Unrelated to type checking.</td> </tr> <tr> - <td><a name="tag-see">@see</a></td> + <td><a name="tag-define">@define</a></td> <td> - <tt>@see Link</tt> + <code>@define {Type} description</code> <p><i>For example:</i></p> <CODE_SNIPPET> + /** @define {boolean} */ + var TR_FLAGS_ENABLE_DEBUG = true; + /** - * Adds a single item, recklessly. - * @see #addSafely - * @see goog.Collect - * @see goog.RecklessAdder#add - ... + * @define {boolean} Whether we know at compile-time that + * the browser is IE. + */ + goog.userAgent.ASSUME_IE = false; </CODE_SNIPPET> </td> - <td>Reference a lookup to another class function or method.</td> - <td>Unrelated to type checking.</td> + <td> + Indicates a constant that can be overridden by the compiler at + compile-time. In the example, the compiler flag + <code>--define='goog.userAgent.ASSUME_IE=true'</code> + could be specified in the BUILD file to indicate that the + constant <code>goog.userAgent.ASSUME_IE</code> should be replaced + with <code>true</code>. + </td> </tr> <tr> - <td><a name="tag-fileoverview">@fileoverview</a></td> + <td><a name="tag-deprecated">@deprecated</a></td> <td> - <tt>@fileoverview Description</tt> + <code>@deprecated Description</code> <p><i>For example:</i></p> <CODE_SNIPPET> /** - * @fileoverview Utilities for doing things that require this very long - * but not indented comment. - * @author kuth@google.com (Uthur Pendragon) + * Determines whether a node is a field. + * @return {boolean} True if the contents of + * the element are editable, but the element + * itself is not. + * @deprecated Use isField(). */ + BN_EditUtil.isTopEditableField = function(node) { + // ... + }; </CODE_SNIPPET> </td> - <td>Makes the comment block provide file level information.</td> - <td>Unrelated to type checking.</td> + <td> + Used to tell that a function, method or property should not be + used any more. Always provide instructions on what callers + should use instead. + </td> </tr> <tr> - <td><a name="tag-constructor">@constructor</a></td> + <td><a name="tag-dict">@dict</a></td> <td> - <tt>@constructor</tt> + <code>@dict Description</code> <p><i>For example:</i></p> <CODE_SNIPPET> /** - * A rectangle. * @constructor + * @dict */ - function GM_Rect() { - ... + function Foo(x) { + this['x'] = x; } + var obj = new Foo(123); + var num = obj.x; // warning + + (/** @dict */ { x: 1 }).x = 123; // warning </CODE_SNIPPET> </td> <td> - Used in a class's documentation to indicate the constructor. + When a constructor (<code>Foo</code> in the example) is + annotated with <code>@dict</code>, you can only use the + bracket notation to access the properties of <code>Foo</code> + objects. + The annotation can also be used directly on object literals. </td> - <td> - Yes. If omitted the compiler will prohibit instantiation. - </td> </tr> <tr> - <td><a name="tag-interface">@interface</a></td> + <td><a name="tag-enum">@enum</a></td> <td> - <tt>@interface</tt> + <code>@enum {Type}</code> <p><i>For example:</i></p> <CODE_SNIPPET> /** - * A shape. - * @interface + * Enum for tri-state values. + * @enum {number} */ - function Shape() {}; - Shape.prototype.draw = function() {}; + project.TriState = { + TRUE: 1, + FALSE: -1, + MAYBE: 0 + }; + </CODE_SNIPPET> + </td> + </tr> - /** - * A polygon. - * @interface - * @extends {Shape} - */ - function Polygon() {}; - Polygon.prototype.getSides = function() {}; + <tr> + <td><a name="tag-export">@export</a></td> + <td> + <code>@export</code> + <p><i>For example:</i></p> + <CODE_SNIPPET> + /** @export */ + foo.MyPublicClass.prototype.myPublicMethod = function() { + // ... + }; </CODE_SNIPPET> </td> - <td>Used to indicate that the function defines an inteface.</td> <td> - Yes. The compiler will warn about instantiating an interface. + <p>Given the code on the left, when the compiler is run with + the <code>--generate_exports</code> flag, it will generate the + code:</p> + <CODE_SNIPPET> + goog.exportSymbol('foo.MyPublicClass.prototype.myPublicMethod', + foo.MyPublicClass.prototype.myPublicMethod); + </CODE_SNIPPET> + <p>which will export the symbols to uncompiled code. + Code that uses the <code>@export</code> annotation must either</p> + <ol> + <li>include <code>//javascript/closure/base.js</code>, or</li> + <li>define both <code>goog.exportSymbol</code> and + <code>goog.exportProperty</code> with the same method + signature in their own codebase.</li> + </ol> </td> </tr> <tr> - <td><a name="tag-type">@type</a></td> + <td><a name="tag-expose">@expose</a></td> <td> - <tt> - @type Type<br/> - @type {Type} - </tt> + <code>@expose</code> <p><i>For example:</i></p> <CODE_SNIPPET> - /** - * The message hex ID. - * @type {string} - */ - var hexId = hexId; + /** @expose */ + MyClass.prototype.exposedProperty = 3; </CODE_SNIPPET> </td> <td> - Identifies the type of a variable, property, or expression. - Curly braces are not required around most types, but some - projects mandate them for all types, for consistency. + <p> + Declares an exposed property. Exposed properties + will not be removed, or renamed, or collapsed, + or optimized in any way by the compiler. No properties + with the same name will be able to be optimized either. + </p> + + <p> + <code>@expose</code> should never be used in library code, + because it will prevent that property from ever getting + removed. + </p> </td> - <td>Yes</td> </tr> <tr> <td><a name="tag-extends">@extends</a></td> <td> - <tt> + <code> @extends Type<br/> @extends {Type} - </tt> + </code> <p><i>For example:</i></p> <CODE_SNIPPET> /** @@ -2279,19 +2705,60 @@ </CODE_SNIPPET> </td> <td> - Used with @constructor to indicate that a class inherits from - another class. Curly braces around the type are optional. + Used with <code>@constructor</code> to indicate that a class + inherits from another class. Curly braces around the type are + optional. </td> - <td>Yes</td> </tr> <tr> + <td><a name="tag-externs">@externs</a></td> + <td> + <code>@externs</code> + <p><i>For example:</i></p> + <CODE_SNIPPET> + /** + * @fileoverview This is an externs file. + * @externs + */ + + var document; + </CODE_SNIPPET> + </td> + <td> + <p> + Declares an + + externs file. + </p> + + + </td> + </tr> + + <tr> + <td><a name="tag-fileoverview">@fileoverview</a></td> + <td> + <code>@fileoverview Description</code> + <p><i>For example:</i></p> + <CODE_SNIPPET> + /** + * @fileoverview Utilities for doing things that require this very long + * but not indented comment. + * @author kuth@google.com (Uthur Pendragon) + */ + </CODE_SNIPPET> + </td> + <td>Makes the comment block provide file level information.</td> + </tr> + + <tr> <td><a name="tag-implements">@implements</a></td> <td> - <tt> + <code> @implements Type<br/> @implements {Type} - </tt> + </code> <p><i>For example:</i></p> <CODE_SNIPPET> /** @@ -2312,20 +2779,67 @@ </CODE_SNIPPET> </td> <td> - Used with @constructor to indicate that a class implements an - interface. Curly braces around the type are optional. + Used with <code>@constructor</code> to indicate that a class + implements an interface. Curly braces around the type are + optional. </td> + </tr> + + <tr> + <td><a name="tag-inheritDoc">@inheritDoc</a></td> <td> - Yes. The compiler will warn about incomplete implementations - of interfaces. + <code>@inheritDoc</code> + <p><i>For example:</i></p> + <CODE_SNIPPET> + /** @inheritDoc */ + project.SubClass.prototype.toString() { + // ... + }; + </CODE_SNIPPET> </td> + <td> + <p style="font-weight:bold">Deprecated. Use + <code>@override</code> instead.</p> + + Indicates that a method or property of a subclass + intentionally hides a method or property of the superclass, + and has exactly the same documentation. Notice that + <code>@inheritDoc</code> implies <code>@override</code> + </td> </tr> <tr> + <td><a name="tag-interface">@interface</a></td> + <td> + <code>@interface</code> + <p><i>For example:</i></p> + <CODE_SNIPPET> + /** + * A shape. + * @interface + */ + function Shape() {}; + Shape.prototype.draw = function() {}; + + /** + * A polygon. + * @interface + * @extends {Shape} + */ + function Polygon() {}; + Polygon.prototype.getSides = function() {}; + </CODE_SNIPPET> + </td> + <td> + Used to indicate that the function defines an interface. + </td> + </tr> + + <tr> <td><a name="tag-lends">@lends</a></td> <td> - <tt>@lends objectName</tt><br/> - <tt>@lends {objectName}</tt> + <code>@lends objectName</code><br/> + <code>@lends {objectName}</code> <p><i>For example:</i></p> <CODE_SNIPPET> goog.object.extend( @@ -2343,402 +2857,435 @@ Notice that the name in braces is not a type name like in other annotations. It's an object name. It names the object on which the properties are "lent". - For example, <tt>@type {Foo}</tt> means "an instance of Foo", - but <tt>@lends {Foo}</tt> means "the constructor Foo".<p/> + For example, <code>@type {Foo}</code> means "an instance of Foo", + but <code>@lends {Foo}</code> means "the constructor Foo".<p/> The <a href="http://code.google.com/p/jsdoc-toolkit/wiki/TagLends"> JSDoc Toolkit docs</a> have more information on this annotation. </td> - <td>Yes</td> </tr> <tr> - <td><a name="tag-private">@private</a></td> + <td><a name="tag-license">@license</a> or + <a name="tag-preserve">@preserve</a></td> <td> - <tt>@private</tt> + <code>@license Description</code> <p><i>For example:</i></p> <CODE_SNIPPET> /** - * Handlers that are listening to this logger. - * @type Array.&lt;Function&gt; - * @private + * @preserve Copyright 2009 SomeThirdParty. + * Here is the full license text and copyright + * notice for this file. Note that the notice can span several + * lines and is only terminated by the closing star and slash: */ - this.handlers_ = []; </CODE_SNIPPET> </td> <td> - Used in conjunction with a trailing underscore on the method - or property name to indicate that the member is - <a href="#Visibility__private_and_protected_fields_">private</a>. - Trailing underscores may eventually be deprecated as tools are - updated to enforce <tt>@private</tt>. + Anything marked by <code>@license</code> or + <code>@preserve</code> will be retained by the compiler and + output at the top of the compiled code for that file. This + annotation allows important notices (such as legal licenses or + copyright text) to survive compilation unchanged. Line breaks + are preserved. </td> - <td>Enforced with a flag.</td> </tr> + + + + <tr> - <td><a name="tag-protected">@protected</a></td> + <td><a name="tag-noalias">@noalias</a></td> <td> - <tt>@protected</tt> + <code>@noalias</code> <p><i>For example:</i></p> <CODE_SNIPPET> - /** - * Sets the component's root element to the given element. Considered - * protected and final. - * @param {Element} element Root element for the component. - * @protected - */ - goog.ui.Component.prototype.setElementInternal = function(element) { - // ... - }; + /** @noalias */ + function Range() {} </CODE_SNIPPET> </td> <td> - Used to indicate that the member or property is - <a href="#Visibility__private_and_protected_fields_">protected</a>. - Should be used in conjunction with names with no trailing - underscore. + Used in an externs file to indicate to the compiler that the + variable or function should not be aliased as part of the + alias externals pass of the compiler. </td> - <td>Enforced with a flag.</td> </tr> <tr> - <td><a name="tag-this">@this</a></td> + <td><a name="tag-nocompile">@nocompile</a></td> <td> - <tt> - @this Type<br/> - @this {Type} - </tt> + <code>@nocompile</code> <p><i>For example:</i></p> <CODE_SNIPPET> - pinto.chat.RosterWidget.extern('getRosterElement', - /** - * Returns the roster widget element. - * @this pinto.chat.RosterWidget - * @return {Element} - */ - function() { - return this.getWrappedComponent_().getElement(); - }); + /** @nocompile */ + + // JavaScript code </CODE_SNIPPET> </td> <td> - The type of the object in whose context a particular method is - called. Required when the <tt>this</tt> keyword is referenced - from a function that is not a prototype method. + Used at the top of a file to tell the compiler to parse this + file but not compile it. + Code that is not meant for compilation and should be omitted + from compilation tests (such as bootstrap code) uses this + annotation. + Use sparingly. </td> - <td>Yes</td> </tr> <tr> - <td><a name="tag-supported">@supported</a></td> + <td><a name="tag-nosideeffects">@nosideeffects</a></td> <td> - <tt>@supported Description</tt> + <code>@nosideeffects</code> <p><i>For example:</i></p> <CODE_SNIPPET> - /** - * @fileoverview Event Manager - * Provides an abstracted interface to the - * browsers' event systems. - * @supported So far tested in IE6 and FF1.5 - */ + /** @nosideeffects */ + function noSideEffectsFn1() { + // ... + } + + /** @nosideeffects */ + var noSideEffectsFn2 = function() { + // ... + }; + + /** @nosideeffects */ + a.prototype.noSideEffectsFn3 = function() { + // ... + }; </CODE_SNIPPET> </td> <td> - Used in a fileoverview to indicate what browsers are supported - by the file. + This annotation can be used as part of function and + constructor declarations to indicate that calls to the + declared function have no side-effects. This annotation + allows the compiler to remove calls to these functions if the + return value is not used. </td> - <td>Unrelated to type checking.</td></tr> + </tr> <tr> - <td><a name="tag-enum">@enum</a></td> + <td><a name="tag-override">@override</a></td> <td> - <tt>@enum {Type}</tt> + <code>@override</code> <p><i>For example:</i></p> <CODE_SNIPPET> /** - * Enum for tri-state values. - * @enum {number} + * @return {string} Human-readable representation of project.SubClass. + * @override */ - project.TriState = { - TRUE: 1, - FALSE: -1, - MAYBE: 0 + project.SubClass.prototype.toString = function() { + // ... }; </CODE_SNIPPET> </td> - <td>Used for documenting enum types.</td> - <td>Fully supported. If Type is omitted, number assumed.</td> + <td> + Indicates that a method or property of a subclass + intentionally hides a method or property of the superclass. If + no other documentation is included, the method or property + also inherits documentation from its superclass. + </td> </tr> <tr> - <td><a name="tag-deprecated">@deprecated</a></td> + <td><a name="tag-param">@param</a></td> <td> - <tt>@deprecated Description</tt> + <code>@param {Type} varname Description</code> <p><i>For example:</i></p> <CODE_SNIPPET> /** - * Determines whether a node is a field. - * @return {boolean} True if the contents of - * the element are editable, but the element - * itself is not. - * @deprecated Use isField(). + * Queries a Baz for items. + * @param {number} groupNum Subgroup id to query. + * @param {string|number|null} term An itemName, + * or itemId, or null to search everything. */ - BN_EditUtil.isTopEditableField = function(node) { + goog.Baz.prototype.query = function(groupNum, term) { // ... }; </CODE_SNIPPET> </td> <td> - Used to tell that a function, method or property should not be - used any more. Always provide instructions on what callers - should use instead. + Used with method, function and constructor calls to document + the arguments of a function.<p/> + + <a href="#JsTypes">Type</a> + names must be enclosed in curly braces. If the type + is omitted, the compiler will not type-check the parameter. </td> - <td>Unrelated to type checking</td> </tr> <tr> - <td><a name="tag-override">@override</a></td> + <td><a name="tag-private">@private</a></td> <td> - <tt>@override</tt> + <code>@private</code><br/> + <code>@private {type}</code> <p><i>For example:</i></p> <CODE_SNIPPET> /** - * @return {string} Human-readable representation of project.SubClass. - * @override + * Handlers that are listening to this logger. + * @private {!Array.&lt;Function&gt;} */ - project.SubClass.prototype.toString() { - // ... - }; + this.handlers_ = []; </CODE_SNIPPET> </td> <td> - Indicates that a method or property of a subclass - intentionally hides a method or property of the superclass. If - no other documentation is included, the method or property - also inherits documentation from its superclass. + Used in conjunction with a trailing underscore on the method + or property name to indicate that the member is + <a href="#Visibility__private_and_protected_fields_">private</a> and final. </td> - <td>Yes</td> </tr> <tr> - <td><a name="tag-inheritDoc">@inheritDoc</a></td> + <td><a name="tag-protected">@protected</a></td> <td> - <tt>@inheritDoc</tt> + <code>@protected</code><br/> + <code>@protected {type}</code> <p><i>For example:</i></p> <CODE_SNIPPET> - /** @inheritDoc */ - project.SubClass.prototype.toString() { + /** + * Sets the component's root element to the given element. + * @param {Element} element Root element for the component. + * @protected + */ + goog.ui.Component.prototype.setElementInternal = function(element) { // ... }; </CODE_SNIPPET> </td> <td> - Indicates that a method or property of a subclass - intentionally hides a method or property of the superclass, - and has exactly the same documentation. Notice that - @inheritDoc implies @override. + Used to indicate that the member or property is + <a href="#Visibility__private_and_protected_fields_">protected</a>. + Should be used in conjunction with names with no trailing + underscore. </td> - <td>Yes</td> </tr> <tr> - <td><a name="tag-code">@code</a></td> + <td><a name="tag-public">@public</a></td> <td> - <tt>{@code ...}</tt> + <code>@public</code><br/> + <code>@public {type}</code> <p><i>For example:</i></p> <CODE_SNIPPET> /** - * Moves to the next position in the selection. - * Throws {@code goog.iter.StopIteration} when it - * passes the end of the range. - * @return {Node} The node at the next position. + * Whether to cancel the event in internal capture/bubble processing. + * @public {boolean} + * @suppress {visiblity} Referencing this outside this package is strongly + * discouraged. */ - goog.dom.RangeIterator.prototype.next = function() { + goog.events.Event.prototype.propagationStopped_ = false; + </CODE_SNIPPET> + </td> + <td> + Used to indicate that the member or property is public. Variables and + properties are public by default, so this annotation is rarely necessary. + Should only be used in legacy code that cannot be easily changed to + override the visibility of members that were named as private variables. + </td> + </tr> + + <tr> + <td><a name="tag-return">@return</a></td> + <td> + <code>@return {Type} Description</code> + <p><i>For example:</i></p> + <CODE_SNIPPET> + /** + * @return {string} The hex ID of the last item. + */ + goog.Baz.prototype.getLastId = function() { // ... + return id; }; </CODE_SNIPPET> </td> <td> - Indicates that a term in a JSDoc description is code so it may - be correctly formatted in generated documentation. + Used with method and function calls to document the return + type. When writing descriptions for boolean parameters, + prefer "Whether the component is visible" to "True if the + component is visible, false otherwise". If there is no return + value, do not use an <code>@return</code> tag.<p/> + + <a href="#JsTypes">Type</a> + names must be enclosed in curly braces. If the type + is omitted, the compiler will not type-check the return value. </td> - <td>Not applicable.</td> </tr> <tr> - <td><a name="tag-license">@license</a> or - <a name="tag-preserve">@preserve</a></td> + <td><a name="tag-see">@see</a></td> <td> - <tt>@license Description</tt> + <code>@see Link</code> <p><i>For example:</i></p> <CODE_SNIPPET> /** - * @preserve Copyright 2009 SomeThirdParty. - * Here is the full license text and copyright - * notice for this file. Note that the notice can span several - * lines and is only terminated by the closing star and slash: + * Adds a single item, recklessly. + * @see #addSafely + * @see goog.Collect + * @see goog.RecklessAdder#add + ... + </CODE_SNIPPET> + </td> + <td>Reference a lookup to another class function or method.</td> + </tr> + + <tr> + <td><a name="tag-struct">@struct</a></td> + <td> + <code>@struct Description</code> + <p><i>For example:</i></p> + <CODE_SNIPPET> + /** + * @constructor + * @struct */ + function Foo(x) { + this.x = x; + } + var obj = new Foo(123); + var num = obj['x']; // warning + obj.y = "asdf"; // warning + + Foo.prototype = /** @struct */ { + method1: function() {} + }; + Foo.prototype.method2 = function() {}; // warning </CODE_SNIPPET> </td> <td> - Anything marked by @license or @preserve will be retained by - the compiler and output at the top of the compiled code for - that file. This annotation allows important notices (such as - legal licenses or copyright text) to survive compilation - unchanged. Line breaks are preserved. + When a constructor (<code>Foo</code> in the example) is + annotated with <code>@struct</code>, you can only use the dot + notation to access the properties of <code>Foo</code> objects. + Also, you cannot add new properties to <code>Foo</code> + objects after they have been created. + The annotation can also be used directly on object literals. </td> - <td>Unrelated to type checking.</td> </tr> <tr> - <td><a name="tag-noalias">@noalias</a></td> + <td><a name="tag-supported">@supported</a></td> <td> - <tt>@noalias</tt> + <code>@supported Description</code> <p><i>For example:</i></p> <CODE_SNIPPET> - /** @noalias */ - function Range() {} + /** + * @fileoverview Event Manager + * Provides an abstracted interface to the + * browsers' event systems. + * @supported So far tested in IE6 and FF1.5 + */ </CODE_SNIPPET> </td> <td> - Used in an externs file to indicate to the compiler that the - variable or function should not be aliased as part of the - alias externals pass of the compiler. + Used in a fileoverview to indicate what browsers are supported + by the file. </td> - <td>Unrelated to type checking.</td> </tr> <tr> - <td><a name="tag-define">@define</a></td> + <td><a name="tag-suppress">@suppress</a></td> <td> - <tt>@define {Type} description</tt> + <code> + @suppress {warning1|warning2} + </code> + <code> + @suppress {warning1,warning2} + </code> <p><i>For example:</i></p> <CODE_SNIPPET> - /** @define {boolean} */ - var TR_FLAGS_ENABLE_DEBUG = true; - - /** @define {boolean} */ - goog.userAgent.ASSUME_IE = false; + /** + * @suppress {deprecated} + */ + function f() { + deprecatedVersionOfF(); + } </CODE_SNIPPET> </td> <td> - Indicates a constant that can be overridden by the compiler at - compile-time. In the example, the compiler flag - <tt>--define='goog.userAgent.ASSUME_IE=true'</tt> - could be specified in the BUILD file to indicate that the - constant <tt>goog.userAgent.ASSUME_IE</tt> should be replaced - with <tt>true</tt>. + Suppresses warnings from tools. Warning categories are + separated by <code>|</code> or <code>,</code>. + </td> - <td>Unrelated to type checking.</td> </tr> - - <tr> - <td><a name="tag-export">@export</a></td> + <td><a name="tag-template">@template</a></td> <td> - <tt>@export</tt> + <code>@template</code> <p><i>For example:</i></p> <CODE_SNIPPET> - /** @export */ - foo.MyPublicClass.prototype.myPublicMethod = function() { - // ... + /** + * @param {function(this:T, ...)} fn + * @param {T} thisObj + * @param {...*} var_args + * @template T + */ + goog.bind = function(fn, thisObj, var_args) { + ... }; </CODE_SNIPPET> </td> <td> - <p>Given the code on the left, when the compiler is run with - the <tt>--generate_exports</tt> flag, it will generate the - code:</p> - <CODE_SNIPPET> - goog.exportSymbol('foo.MyPublicClass.prototype.myPublicMethod', - foo.MyPublicClass.prototype.myPublicMethod); - </CODE_SNIPPET> - <p>which will export the symbols to uncompiled code. - Code that uses the <tt>@export</tt> annotation must either</p> - <ol> - <li>include <tt>//javascript/closure/base.js</tt>, or</li> - <li>define both <tt>goog.exportSymbol</tt> and - <tt>goog.exportProperty</tt> with the same method - signature in their own codebase.</li> - </ol> + This annotation can be used to declare a + <a href="#Template_types">template typename</a>. </td> - <td>Unrelated to type checking.</td> </tr> <tr> - <td><a name="tag-const">@const</a></td> + <td><a name="tag-this">@this</a></td> <td> - <tt>@const</tt> + <code> + @this Type<br/> + @this {Type} + </code> <p><i>For example:</i></p> <CODE_SNIPPET> - /** @const */ var MY_BEER = 'stout'; - + pinto.chat.RosterWidget.extern('getRosterElement', /** - * My namespace's favorite kind of beer. - * @const - * @type {string} + * Returns the roster widget element. + * @this pinto.chat.RosterWidget + * @return {Element} */ - mynamespace.MY_BEER = 'stout'; - - /** @const */ MyClass.MY_BEER = 'stout'; + function() { + return this.getWrappedComponent_().getElement(); + }); </CODE_SNIPPET> </td> <td> - <p>Marks a variable as read-only and suitable for inlining. - Generates warnings if it is rewritten.</p> - <p>Constants should also be ALL_CAPS, but the annotation - should help eliminate reliance on the naming convention. - Although @final is listed at jsdoc.org and is supported as - equivalent to @const in the compiler, it is discouraged. - @const is consistent with JS1.5's const keyword. Note that - changes to properties of const objects are not currently - prohibited by the compiler (inconsistent with C++ const - semantics). The type declaration can be omitted if it can be - clearly inferred. If present, it must be on its own line. An - additional comment about the variable is optional.</p> + The type of the object in whose context a particular method is + called. Required when the <code>this</code> keyword is referenced + from a function that is not a prototype method. </td> - <td>Supported by type checking.</td> </tr> <tr> - <td><a name="tag-nosideeffects">@nosideeffects</a></td> + <td><a name="tag-type">@type</a></td> <td> - <tt>@nosideeffects</tt> + <code> + @type Type<br/> + @type {Type} + </code> <p><i>For example:</i></p> <CODE_SNIPPET> - /** @nosideeffects */ - function noSideEffectsFn1() { - // ... - }; - - /** @nosideeffects */ - var noSideEffectsFn2 = function() { - // ... - }; - - /** @nosideeffects */ - a.prototype.noSideEffectsFn3 = function() { - // ... - }; + /** + * The message hex ID. + * @type {string} + */ + var hexId = hexId; </CODE_SNIPPET> </td> <td> - This annotation can be used as part of function and - constructor declarations to indicate that calls to the - declared function have no side-effects. This annotation - allows the compiler to remove calls to these functions if the - return value is not used. + Identifies the <a href="#JsTypes">type</a> of a variable, + property, or expression. Curly braces are not required around + most types, but some projects mandate them for all types, for + consistency. </td> - <td>Unrelated to type checking.</td> </tr> <tr> <td><a name="tag-typedef">@typedef</a></td> <td> - <tt>@typedef</tt> + <code>@typedef</code> <p><i>For example:</i></p> <CODE_SNIPPET> /** @typedef {(string|number)} */ @@ -2752,41 +3299,17 @@ </td> <td> This annotation can be used to declare an alias of a more - complex type. + <a href="#Typedefs">complex type</a>. </td> - <td>Yes</td> </tr> - <tr> - <td><a name="tag-externs">@externs</a></td> - <td> - <tt>@externs</tt> - <p><i>For example:</i></p> - <CODE_SNIPPET> - /** - * @fileoverview This is an externs file. - * @externs - */ - - var document; - </CODE_SNIPPET> - </td> - <td> - <p> - Declares an - - externs file. - </p> - - - </td> - <td>No</td> - </tr> </tbody> </table> + + <p> You may also see other types of JSDoc annotations in third-party code. These annotations appear in the @@ -2823,83 +3346,51 @@ </ul> </p> </SUBSECTION> + </BODY> + </STYLEPOINT> - <SUBSECTION title="HTML in JSDoc"> - <p>Like JavaDoc, JSDoc supports many HTML tags, like &lt;code&gt;, - &lt;pre&gt;, &lt;tt&gt;, &lt;strong&gt;, &lt;ul&gt;, &lt;ol&gt;, - &lt;li&gt;, &lt;a&gt;, and others.</p> - - <p>This means that plaintext formatting is not respected. So, don't - rely on whitespace to format JSDoc:</p> - - <BAD_CODE_SNIPPET> - /** - * Computes weight based on three factors: - * items sent - * items received - * last timestamp - */ - </BAD_CODE_SNIPPET> - - <p>It'll come out like this:</p> - - <tt>Computes weight based on three factors: items sent items received items received</tt> - - <p>Instead, do this:</p> - - <CODE_SNIPPET> - /** - * Computes weight based on three factors: - * &lt;ul&gt; - * &lt;li&gt;items sent - * &lt;li&gt;items received - * &lt;li&gt;last timestamp - * &lt;/ul&gt; - */ - </CODE_SNIPPET> - - <p>Also, don't include HTML or HTML-like tags unless you want them to - be interpreted as HTML.</p> - - <BAD_CODE_SNIPPET> - /** - * Changes &lt;b&gt; tags to &lt;span&gt; tags. - */ - </BAD_CODE_SNIPPET> - - <p>It'll come out like this:</p> - - <tt>Changes <b> tags to <span> tags.</span></b></tt> - - <p>On the other hand, people need to be able to read this in its - plaintext form too, so don't go overboard with the HTML:</p> - - <BAD_CODE_SNIPPET> - /** - * Changes &amp;lt;b&amp;gt; tags to &amp;lt;span&amp;gt; tags. - */ - </BAD_CODE_SNIPPET> - - <p>People will know what you're talking about if you leave the - angle-brackets out, so do this:</p> - - <CODE_SNIPPET> - /** - * Changes 'b' tags to 'span' tags. - */ - </CODE_SNIPPET> - </SUBSECTION> + <STYLEPOINT title="Providing Dependencies With goog.provide"> + <SUMMARY> + Only provide top-level symbols. + </SUMMARY> + <BODY> + <p> + All members defined on a class should be in the same file. So, only + top-level classes should be provided in a file that contains multiple + members defined on the same class (e.g. enums, inner classes, etc). + </p> + <p>Do this:</p> + <CODE_SNIPPET> + goog.provide('namespace.MyClass'); + </CODE_SNIPPET> + <p>Not this:</p> + <BAD_CODE_SNIPPET> + goog.provide('namespace.MyClass'); + goog.provide('namespace.MyClass.Enum'); + goog.provide('namespace.MyClass.InnerClass'); + goog.provide('namespace.MyClass.TypeDef'); + goog.provide('namespace.MyClass.CONSTANT'); + goog.provide('namespace.MyClass.staticMethod'); + </BAD_CODE_SNIPPET> + <p> + Members on namespaces may also be provided: + </p> + <CODE_SNIPPET> + goog.provide('foo.bar'); + goog.provide('foo.bar.method'); + goog.provide('foo.bar.CONSTANT'); + </CODE_SNIPPET> </BODY> </STYLEPOINT> <STYLEPOINT title="Compiling"> - <SUMMARY>Encouraged</SUMMARY> + <SUMMARY>Required</SUMMARY> <BODY> <p>Use of JS compilers such as the <a href="http://code.google.com/closure/compiler/">Closure Compiler</a> - is encouraged.</p> + is required for all customer-facing code.</p> @@ -2977,7 +3468,7 @@ <SUBSECTION title="Conditional (Ternary) Operator (?:)"> <p>Instead of this:</p> <CODE_SNIPPET> - if (val != 0) { + if (val) { return foo(); } else { return bar(); @@ -3057,40 +3548,6 @@ </BAD_CODE_SNIPPET> </SUBSECTION> - <SUBSECTION title="Use join() to Build Strings"> - <p>It is common to see this:</p> - <BAD_CODE_SNIPPET> - function listHtml(items) { - var html = '&lt;div class="foo"&gt;'; - for (var i = 0; i &lt; items.length; ++i) { - if (i &gt; 0) { - html += ', '; - } - html += itemHtml(items[i]); - } - html += '&lt;/div&gt;'; - return html; - } - </BAD_CODE_SNIPPET> - - <p>but this is slow in Internet Explorer, so it is better to do - this:</p> - <CODE_SNIPPET> - function listHtml(items) { - var html = []; - for (var i = 0; i &lt; items.length; ++i) { - html[i] = itemHtml(items[i]); - } - return '&lt;div class="foo"&gt;' + html.join(', ') + '&lt;/div&gt;'; - } - </CODE_SNIPPET> - - <p>You can also use an array as a stringbuilder, and convert it into - a string with <code>myArray.join('')</code>. Note that since - assigning values to an array is faster than using - <code>push()</code> you should use assignment where possible.</p> - </SUBSECTION> - <SUBSECTION title="Iterating over Node Lists"> <p>Node lists are often implemented as node iterators with a filter. This means that getting a property like length is O(n), and @@ -3155,7 +3612,7 @@ </PARTING_WORDS> <p align="right"> - Revision 2.11 + Revision 2.93 </p>
If you want to be updated about similar snippets, Sign in and follow our Channels

blog comments powered by Disqus