Changes between Version 2 and Version 3 of CodeDocumentation


Ignore:
Timestamp:
Feb 6, 2014, 1:07:02 PM (5 years ago)
Author:
Anna Tomanek
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • CodeDocumentation

    v2 v3  
    1 = JSDuck documentation guide =
    2 
    3 Starting from CKEditor 4 we use [https://github.com/senchalabs/jsduck JSDuck] documentation generator, previously it was [http://code.google.com/p/jsdoc-toolkit/ JSDoc].
    4 
    5 JSDuck's comments format differs from JSDoc's and both generators have different features lists. Thus, entire documentation has been reformatted in new, consistent way.
    6 
    7 == Useful links ==
    8 
    9 * [https://github.com/senchalabs/jsduck JSDuck's Github page]
    10 * [https://github.com/senchalabs/jsduck/wiki/Guide Guide]
    11 * [https://github.com/senchalabs/jsduck/wiki/Tags Tags list]
    12 * [http://daringfireball.net/projects/markdown/basics Markdown format - basics]
    13 
    14 == JSDuck vs JSDoc - important differences ==
    15 
    16 * JSDuck has Markdown support. HTML entities may still be used, but try to avoid them in favor of Markdown. Note that HTML in code samples (indented blocks) and {{{`pre-formatted`}}} will be encoded.
    17 * JSDuck does not accept these tags: {{{@namespace}}}, {{{@name}}}, {{{@constant}}}, {{{@augments}}}, {{{@field}}}, {{{@type}}} (deprecated), {{{@default}}} and more (I listed only those which we were using).
    18 * JSDuck accepts new tags: {{{@cfg}}}, {{{@member}}}, {{{@chainable}}}, {{{@inherits}}}, {{{@method}}}, {{{@mixins}}}, {{{@readonly}}}, {{{@singleton}}} and [https://github.com/senchalabs/jsduck/wiki/Tags more].
    19 * Many of shared tags have different format in JSDuck (e.g. {{{@example}}} creates live examples, standard code samples are just indented). So be careful.
    20 * JSDuck does not parse code searching for classes and properties. Thus, it will only find those API elements which have at least their preceding {{{/** */}}} doc comments.
    21 * JSDuck recognizes names of API elements (methods, classes, events, config vars, properties, etc), method definitions (with arguments list) and properties (their type and default value too if possible). Thus, these information does not have to be specified in some cases.
    22 * Classes' definitions may be opened multiple times - it's useful when class's methods and properties are defined in more than one file or place in the code.
    23 * There's no list of files in JSDuck, so old {{{@license}}} and {{{@fileOverview}}} tags are kept for other purposes (and thanks to [https://github.com/senchalabs/jsduck/wiki/Custom-tags custom tags] they work in JSDuck like {{{@ignore}}}).
    24 * There are no namespaces in JSDuck, so the packages tree is auto-generated based on the classes tree and {{{@member}}} tags.
    25 * All properties, events, etc. defined under the class definition will be assigned to this class, so there's no need to specify {{{@member}}}.
    26 
    27 == Docs formats ==
    28 
    29 === File header ===
    30 
    31 {{{
    32 /**
    33  * @license Copyright (c) 2003-2012, CKSource - Frederico Knabben. All rights reserved.
    34  * For licensing, see LICENSE.html or http://ckeditor.com/license
    35  */
    36 
    37 /**
    38  * @fileOverview Defines the {@link CKEDITOR.editor} class, which represents an
    39  * editor instance.
    40  */
    41 }}}
    42 
    43 Both comments will be ignored and they are not required.
    44 
    45 **Note** that since {{{@fileOverview}}} comments are ignored, they weren't reformatted, so they may contain old JSDoc format.
    46 
    47 === Class ===
    48 
    49 {{{
    50 /**
    51  * Represents an editor instance. This constructor should be rarely
    52  * used, in favor of the {@link CKEDITOR} editor creation functions.
    53  *
    54  *              var editor = new CKEDITOR.editor();
    55  *              editor.setSomething( name, {
    56  *                      value: 1
    57  *              } );
    58  *
    59  * @since 3.0
    60  * @private
    61  * @class CKEDITOR.editor
    62  * @extends CKEDITOR.parent
    63  * @mixins CKEDITOR.event
    64  * @mixins CKEDITOR.whatever
    65  * @constructor Creates an editor class instance.
    66  * @param {Object} [instanceConfig] Configuration values for this specific instance.
    67  * @param {Number} [mode=CKEDITOR.SOURCE_MODE] The element creation mode to be used by this editor.
    68  * will be created.
    69  *
    70  * Possible values are:
    71  *
    72  * * `CKEDITOR.SOURCE_MODE` - desc 1,
    73  * * `CKEDITOR.WYSIWYG_MODE` - desc 2 long long long
    74  *      long long long long long,
    75  * * `CKEDITOR.ANOTHER_MODE` - desc 3.
    76  *
    77  * @param {CKEDITOR.dom.element} [element] The DOM element upon which this editor
    78  * will be created.
    79  * @see CKEDITOR.editable
    80  * @see CKEDITOR.cofing#someVar
    81  */
    82 CKEDITOR.editor = function( ) {
    83         // ...
    84 }}}
    85 
    86 This is the example of class definition. It contains so many tags to show their correct order.
    87 
    88 The minimal class doc:
    89 
    90 {{{
    91 /**
    92  * Represents an editor instance. This constructor should be rarely
    93  * used, in favor of the {@link CKEDITOR} editor creation functions.
    94  *
    95  * @class
    96  */
    97 CKEDITOR.editor = function( ) {
    98         // ...
    99 }}}
    100 
    101 And when you want to reopen class declaration in other file:
    102 
    103 {{{
    104 /** @class CKEDITOR.editor */
    105 }}}
    106 
    107 ==== Details ====
    108 
    109 Tags order may look strange, but you can remember it thanks to this description:
    110 
    111 > Since 3.0 there's a private class CKEDITOR.editor which extends CKEDITOR.parent and mixins CKEDITOR.event and CKEDITOR.whatever.
    112 >
    113 > It has a private constructor (switched order - I'll explain this later in the tags list) which accepts following params: ...
    114 >
    115 > See also: ...
    116 
    117 Important tags details:
    118 
    119 * Private classes by default won't be visible in the packages tree.
    120 * Good example of difference between "mixins" and "extends" is that ```CKEDITOR.event``` is mixed in various other classes and ```CKEDITOR.dom.*``` structure is based on extending parent classes.
    121 * Constructor is in fact a separate documentation "instance", because it will be listed with methods. Thus, it may have its own {{{@private}}}, but it has to be placed below it, because everything before will be the part of class description. However two {{{@private}}} tags in one comment won't be accepted by JSLinter, so the doc then should be split into two comments.
    122 
    123     Another conclusion is that constructor may be declared completely independently from class, what's useful when {{{CKEDITOR.tools.createClass}}} has been used.
    124 
    125     And the last conclusion is that in the first example {{{@see}}} tags will the part of constructor's definition, not class. Thus they may be also placed after mixins.
    126 
    127 === Property and Config variable ===
    128 
    129 {{{
    130 /**
    131  * A unique identifier of this editor instance.
    132  *
    133  * **Note:** It will be originated from the ID or name
    134  * attribute of the {@link #element}, otherwise a name pattern of
    135  * `'editor{n}'` will be used.
    136  *
    137  * @private
    138  * @readonly
    139  * @static
    140  * @property {String/Boolean} [complicatedName=default value]
    141  * @member CKEDITOR.editor
    142  * @see CKEDITOR.whatever
    143  */
    144 obj[ 'complicated' + 'Name' ] = this.name || genEditorName();
    145 }}}
    146 
    147 The minimal property doc:
    148 
    149 {{{
    150 /**
    151  * Property desc (even this may be omitted, but it's better to always describe property).
    152  */
    153 this.propertyName = 'value';
    154 }}}
    155 
    156 Which will be, by the JSDuck, recognized as {{{@property {String} [propertyName='value']}}} and will be assigned to the class defined earlier in the file.
    157 
    158 Partial:
    159 
    160 {{{
    161 /**
    162  * Property desc.
    163  *
    164  * @property {String} [=config.something (value taken from configuration)]
    165  */
    166 this.propertyName = this.config.something;
    167 }}}
    168 
    169 Basic:
    170 
    171 {{{
    172 /**
    173  * Property desc.
    174  *
    175  * @property propertyName
    176  */
    177 this.propertyName = this.config.something;
    178 }}}
    179 
    180 ==== Details ====
    181 
    182 * JSDuck's type definitions are awesome - [https://github.com/senchalabs/jsduck/wiki/Type-Definitions read more about them].
    183 * Property name, type and default value may be automatically recognized.
    184 * Default value doesn't have to be a JS code, so in the "Partial" example JSDuck will print: "Defaults to: config.something (value taken...)".
    185 * If property isn't defined below a class definition or it belongs to a different class, then {{{@member}}} has to be used. Specifying namespace in {{{@property}}} isn't possible.
    186 
    187 ==== Config variables ====
    188 
    189 To define config var instead of property:
    190 
    191 * Use {{{@cfg}}} instead of {{{@property}}}. Format is the same.
    192 * {{{@private}}}, {{{@readonly}}}, {{{@static}}} may not work (haven't been tested).
    193 
    194 === Method and Event ===
    195 
    196 {{{
    197 /**
    198  * The the {@link CKEDITOR.dom.element} representing and element. If the
    199  * element is a native DOM element, it will be transformed into a valid
    200  * CKEDITOR.dom.element object.
    201  *
    202  *              var element = new CKEDITOR.dom.element( 'span' );
    203  *              alert( element == CKEDITOR.dom.element.get( element ) ); // true
    204  *
    205  *              var element = document.getElementById( 'myElement' );
    206  *              alert( CKEDITOR.dom.element.get( element ).getName() ); // (e.g.) 'p'
    207  *
    208  * @private
    209  * @static
    210  * @method complicatedName
    211  * @member CKEDITOR.editor
    212  * @param {String/Object} element Element's id or name or native DOM element.
    213  * @param {Function} fn Callback.
    214  * @param {String} fn.firstArg Callback's first argument.
    215  * @param {Number} fn.secondArg Callback's second argument.
    216  * @param {String} [name='default value']
    217  * @returns {CKEDITOR.dom.element} The transformed element.
    218  */
    219 this[ 'complicated' + 'Name' ] = (function() {
    220         return function() {
    221         };
    222 }());
    223 }}}
    224 
    225 Typical:
    226 
    227 {{{
    228 /**
    229  * Method desc.
    230  *
    231  * @param {String/Object} element Element's id or name or native DOM element.
    232  * @param {String} [name='default value']
    233  * @returns {CKEDITOR.dom.element} The transformed element.
    234  */
    235 this.methodName = function() {
    236         // ...
    237 };
    238 }}}
    239 
    240 ==== Details ====
    241 
    242 * {{{@method}}} tag has to be used when it's not clear that this is a method (e.g. closure returning function was used or reference to function defined elsewhere) or method's name isn't obvious.
    243 * Callback's arguments may be defined. Also - if method returns object, its properties may be defined too - [https://github.com/senchalabs/jsduck/wiki/@return read more].
    244 * Both {{{@return}}} and {{{@returns}}} are accepted, but use the latter one.
    245 
    246 ==== Events ====
    247 
    248 To define event instead of method:
    249 
    250 * Use {{{@event}}} instead of {{{@method}}} - usually you'll have to provide the name.
    251 * {{{@returns}}} isn't accepted.
    252 
    253 == Various rules ==
    254 
    255 * Always leave one blank line between textual comment and the first tag.
    256 * Separate all block (paragraphs, code samples, etc.) with one blank line.
    257 * Code samples indent with at least two tabs after {{{'*'}}} and remember - **no spaces**.
    258 * Always place dot {{{'.'}}} at the end of the sentence. Sentence starts with upper-case letter.
    259 * Always use single quotes for JS strings, but double quotes for cites, irony, etc. in textual comments.
    260 * Cross-references format for links is: {{{CKEDITOR.name.space#property}}}. If there are more than one event/prop/cfg/method with the same name, then prepend {{{cfg-, property-, method- or event-}}} to the name. Namespace may be omitted if equals to {{{@member}}} or current class. See "Cross-references" section in [https://github.com/senchalabs/jsduck/wiki/Guide JSDuck's guide].
    261 * In default values use real format: {{{CKEDITOR.name.space.property}}}.
    262 * When describing value returned/alerted in the code sample wrap only strings in {{{''}}}. All other types (boolean, number, objects, etc.) should be left unwrapped.
    263 * There's no Integer type in JS and constructors' names should be used as types names - so Boolean, not boolean.
    264 * In textual comments wrap tokens, names from code, JS values, etc. with {{{``}}} - they will be better visible. Remember to wrap strings with {{{''}}} - so: {{{This method may return: `'text text'`.}}}
     1CKEditor code documentation standards are described in the [http://docs.ckeditor.com/#!/guide/dev_code_documentation Developer's Guide].
© 2003 – 2019 CKSource – Frederico Knabben. All rights reserved. | Terms of use | Privacy policy