Confirmed users
764
edits
Labs/Jetpack/Reboot/Style Guide: Difference between revisions
Labs/Jetpack/Reboot/Style Guide (view source)
Revision as of 17:25, 26 January 2010
, 26 January 2010→Comments and Documentation
(→Style) |
|||
| Line 160: | Line 160: | ||
This applies to in-source docs only, not nice docs meant for end users. | This applies to in-source docs only, not nice docs meant for end users. | ||
Javadoc-style | All exported functions should be documented Javadoc-style. Javadocs are conventional throughout Mozilla code. | ||
<pre class="brush:js;toolbar:false;"> | |||
/** | |||
* This function doesn't return a value. | |||
* | |||
* @param foo | |||
* Does the thing with the foo. | |||
* @param bar | |||
* Don't use this. Ever. | |||
*/ | |||
function f(foo, bar) {} | |||
/** | |||
* This function returns a value. | |||
* | |||
* @param foo | |||
* Does the thing with the foo. | |||
* @param bar | |||
* Don't use this. Ever. | |||
* @return Some value. | |||
*/ | |||
function g(foo, bar) {} | |||
</pre> | |||
Documenting function params that are options objects: | Documenting function params that are options objects: | ||
| Line 170: | Line 189: | ||
<pre class="brush:js;toolbar:false;"> | <pre class="brush:js;toolbar:false;"> | ||
/** | /** | ||
* This function takes an options dictionary. | * This function takes an options dictionary. e.g., | ||
* f({ foo: true, bar: "baz" }); | |||
* | * | ||
* @param options | * @param options | ||
| Line 177: | Line 197: | ||
* If true, does the thing with the foo. | * If true, does the thing with the foo. | ||
* @prop bar | * @prop bar | ||
* Don't use this | * Don't use this. Ever. | ||
*/ | */ | ||
function (options) {} | function f(options) {} | ||
</pre> | </pre> | ||
Non-exported functions don't need to be documented this way, but it's encouraged. | |||
All other comments are C++-style. If a comment is a full sentence, capitalize and punctuate it. Full sentences are generally preferable to fragments, but fragments are sometimes more effective. Don't capitalize or punctuate fragments. | |||
== Further Reading == | == Further Reading == | ||
* [https://developer.mozilla.org/En/Developer_Guide/Coding_Style MDC Coding Style Guidelines] | * [https://developer.mozilla.org/En/Developer_Guide/Coding_Style MDC Coding Style Guidelines] | ||