Changes between Initial Version and Version 1 of CodeDocumentation


Ignore:
Timestamp:
Jun 13, 2013, 7:39:14 AM (6 years ago)
Author:
Piotrek Koszuliński
Comment:

Copied from dev-v4.

Legend:

Unmodified
Added
Removed
Modified
  • CodeDocumentation

    v1 v1  
     1= JSDuck documentation guide =
     2
     3Starting 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
     5JSDuck'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
     43Both 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 */
     82CKEDITOR.editor = function( ) {
     83        // ...
     84}}}
     85
     86This is the example of class definition. It contains so many tags to show their correct order.
     87
     88The 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 */
     97CKEDITOR.editor = function( ) {
     98        // ...
     99}}}
     100
     101And when you want to reopen class declaration in other file:
     102
     103{{{
     104/** @class CKEDITOR.editor */
     105}}}
     106
     107==== Details ====
     108
     109Tags 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
     117Important 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 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 */
     144obj[ 'complicated' + 'Name' ] = this.name || genEditorName();
     145}}}
     146
     147The minimal property doc:
     148
     149{{{
     150/**
     151 * Property desc (even this may be omitted, but it's better to always describe property).
     152 */
     153this.propertyName = 'value';
     154}}}
     155
     156Which will be, by the JSDuck, recognized as {{{@property {String} [propertyName='value']}}} and will be assigned to the class defined earlier in the file.
     157
     158Partial:
     159
     160{{{
     161/**
     162 * Property desc.
     163 *
     164 * @property {String} [=config.something (value taken from configuration)]
     165 */
     166this.propertyName = this.config.something;
     167}}}
     168
     169Basic:
     170
     171{{{
     172/**
     173 * Property desc.
     174 *
     175 * @property propertyName
     176 */
     177this.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
     189To 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 */
     219this[ 'complicated' + 'Name' ] = (function() {
     220        return function() {
     221        };
     222}());
     223}}}
     224
     225Typical:
     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 */
     235this.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
     248To 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 and {{{@private}}} and {{{@static}}} may not work (haven't been tested).
     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 {{{'*'}}}.
     258* Wrapped lines of multiline lists indent with five (default 1 + additional 4) spaces.
     259* Always place dot {{{'.'}}} at the end of the sentence. Sentence starts with upper-case letter.
     260* Always use single quotes for JS strings, but double quotes for cites, irony, etc. in textual comments.
     261* 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].
     262* In default values use real format: {{{CKEDITOR.name.space.property}}}.
     263* When describing value returned/alerted in the code sample wrap only strings in {{{''}}}. All other types (boolean, number, objects, etc.) should be left unwrapped.
     264* There's no Integer type in JS and constructors' names should be used as types names - so Boolean, not boolean.
     265* 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'`.}}}
© 2003 – 2019 CKSource – Frederico Knabben. All rights reserved. | Terms of use | Privacy policy