review.tizen.org Git - platform/framework/web/crosswalk-tizen.git/blob

   1 doctrine ([doctrine](http://github.com/Constellation/doctrine)) is JSDoc parser.
   2
   3 [![Build Status](https://travis-ci.org/Constellation/doctrine.svg?branch=master)](https://travis-ci.org/Constellation/doctrine)
   4 [![Coverage Status](https://img.shields.io/coveralls/Constellation/doctrine.svg)](https://coveralls.io/r/Constellation/doctrine?branch=master)
   5 [![Dependency Status](https://david-dm.org/Constellation/doctrine.svg)](https://david-dm.org/Constellation/doctrine)
   6 [![devDependency Status](https://david-dm.org/Constellation/doctrine/dev-status.svg)](https://david-dm.org/Constellation/doctrine#info=devDependencies)
   7 [![Gitter chat](https://badges.gitter.im/Constellation/doctrine.png)](https://gitter.im/Constellation/doctrine)
   8
   9 It is now used by content assist system of [Eclipse Orion](http://www.eclipse.org/orion/) ([detail](http://planetorion.org/news/2012/10/orion-1-0-release/)). And used as JSDoc validator in [ESLint](http://eslint.org/).
  10
  11 Doctrine can be used in a web browser with using browserify.
  12 or in a Node.js application via the package manager:
  13
  14     npm install doctrine
  15
  16 simple example:
  17
  18     doctrine.parse(
  19         [
  20             "/**",
  21             " * This function comment is parsed by doctrine",
  22             " * @param {{ok:String}} userName",
  23             "*/"
  24         ].join('\n'), { unwrap: true });
  25
  26 and gets following information
  27
  28     {
  29         "description": "This function comment is parsed by doctrine",
  30         "tags": [
  31             {
  32                 "title": "param",
  33                 "description": null,
  34                 "type": {
  35                     "type": "RecordType",
  36                     "fields": [
  37                         {
  38                             "type": "FieldType",
  39                             "key": "ok",
  40                             "value": {
  41                                 "type": "NameExpression",
  42                                 "name": "String"
  43                             }
  44                         }
  45                     ]
  46                 },
  47                 "name": "userName"
  48             }
  49         ]
  50     }
  51
  52 see [demo page](http://constellation.github.com/doctrine/demo/index.html) more detail.
  53
  54 ### Options
  55
  56 #### doctrine.parse
  57 We can pass options to `doctrine.parse(comment, options)`.
  58 ```js
  59 {
  60     unwrap: boolean,          // default: false
  61     tags: [ string ] | null,  // default: null
  62     recoverable: boolean,     // default: false
  63     sloppy: boolean,          // default: false
  64     lineNumbers: boolean      // default: false
  65 }
  66 ```
  67
  68 ##### unwrap
  69
  70 When `unwrap` is `true`, doctrine attempt to unwrap comment specific string from a provided comment text. (removes `/**`, `*/` and `*`)
  71 For example, `unwrap` transforms
  72 ```
  73 /**
  74  * @param use
  75  */
  76 ```
  77 to
  78 ```
  79 @param use
  80 ```
  81 If a provided comment has these comment specific strings, you need to specify this `unwrap` option to `true`.
  82
  83 ##### tags
  84
  85 When `tags` array is specified, doctrine only produce tags that is specified in this array.
  86 For example, if you specify `[ 'param' ]`, doctrine only produces `param` tags.
  87 If null is specified, doctrine produces all tags that doctrine can recognize.
  88
  89 ##### recoverable
  90
  91 When `recoverable` is `true`, doctrine becomes `recoverable` - When failing to parse jsdoc comment, doctrine recovers its state and attempt to continue parsing.
  92
  93 ##### sloppy
  94
  95 When `sloppy` is `true`,
  96 ```
  97 @param String [foo]
  98 ```
  99 's `[foo]` is interpreted as a optional parameter, not interpreted as a name of this `@param`.
 100
 101 ##### lineNumbers
 102
 103 When `lineNumbers` is `true`, parsed tags will include a `lineNumber` property indicating the line (relative to the start of the comment block) where each tag is located in the source. So, given the following comment:
 104 ```
 105 /**
 106  * @param {String} foo
 107  * @return {number}
 108  */
 109 ```
 110 The `@param` tag will have `lineNumber: 1`, and the `@return` tag will have `lineNumber: 2`.
 111
 112
 113 ### License
 114
 115 #### doctrine
 116
 117 Copyright (C) 2012 [Yusuke Suzuki](http://github.com/Constellation)
 118  (twitter: [@Constellation](http://twitter.com/Constellation)) and other contributors.
 119
 120 Redistribution and use in source and binary forms, with or without
 121 modification, are permitted provided that the following conditions are met:
 122
 123   * Redistributions of source code must retain the above copyright
 124     notice, this list of conditions and the following disclaimer.
 125
 126   * Redistributions in binary form must reproduce the above copyright
 127     notice, this list of conditions and the following disclaimer in the
 128     documentation and/or other materials provided with the distribution.
 129
 130 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 131 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 132 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 133 ARE DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
 134 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 135 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 136 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 137 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 138 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 139 THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 140
 141 #### esprima
 142
 143 some of functions is derived from esprima
 144
 145 Copyright (C) 2012, 2011 [Ariya Hidayat](http://ariya.ofilabs.com/about)
 146  (twitter: [@ariyahidayat](http://twitter.com/ariyahidayat)) and other contributors.
 147
 148 Redistribution and use in source and binary forms, with or without
 149 modification, are permitted provided that the following conditions are met:
 150
 151   * Redistributions of source code must retain the above copyright
 152     notice, this list of conditions and the following disclaimer.
 153
 154   * Redistributions in binary form must reproduce the above copyright
 155     notice, this list of conditions and the following disclaimer in the
 156     documentation and/or other materials provided with the distribution.
 157
 158 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 159 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 160 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 161 ARE DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
 162 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 163 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 164 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 165 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 166 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 167 THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 168
 169
 170 #### closure-compiler
 171
 172 some of extensions is derived from closure-compiler
 173
 174 Apache License
 175 Version 2.0, January 2004
 176 http://www.apache.org/licenses/