YUIDoc注释编写

最新推荐文章于 2024-05-09 09:56:51 发布
最新推荐文章于 2024-05-09 09:56:51 发布
阅读量2k 收藏
点赞数
分类专栏： javascript 文章标签： JavaScript 前端开发

上面介绍了JS文档和Demo生成工具SmartDoc，本篇开始介绍一下注释的编写。SmartDoc使用的是YUIDoc的引擎，所以的注释规则都一样，先简单介绍下YUIDoc的注释编写。

 

编写注释是一个很繁重的体力活，很多程序员都嫌麻烦不愿意做此事，但是在编写的过程，会让你注意到很多的细节和考虑一些没有想到的地方，会发现很多的问题和优化点。

 

为了比较好的提高效率，从code开始就应该做好规划，组织文件、模块、代码；将单元测试和注释以及demo综合考虑，有效的重用；

当然无论怎么样都使用smartDoc都会比起单独的开发文档和demo要快捷的多。

推荐sublime下的注释插件DocBlockr, 键入/**后+ tab，可以自动根据后面的js内容自动生成注释模板，如下：

复制代码 
/**
 * [format description]
 * @param  {[type]} tmpl       [description]
 * @param  {[type]} data       [description]
 * @param  {[type]} encodeType [description]
 * @return {[type]}            [description]
 */
function format(tmpl, data, encodeType) {
}
复制代码

 

注释标记

 

以 /** 开始， */ 结束，以@指定类型

复制代码 
//第一种方式
/**
　 desc
  @....
  @....
*/

//第二种方式
/**
 * desc
 * @....
 * @....
*/
复制代码

　　

　　* 第二种方式与第一种不同的时，注释的内容会根据*的位置对齐；两种方式可以混用但不建议使用，会使排版很困难。

　　* 注释是可以空着写的，不需要非要跟着代码，yuidoc只会扫描/** .... */ 的内容描述中;

　　* 描述desc可以使用html

　　* 支持markdown

　　* 支持录入api链接crosslink，格式如：{{#crossLink "module.class/method"}}{{/crossLink}}，例子见@class说明

 

主标签

 

标签名 注释 效果 详细描述
 @module  
复制代码 
/**
 * This is my example module
 * @module ExampleModule
 * @example
 *
 *     var bar;
 *
 */
复制代码

 

 模块标签;

所有在之后的@classs都会归类到此module下；

一个js文件最好定义一个module；

一个文件中多个module，yuidoc的扫描有时会乱掉;

其他js文件对此module扩展的话，使用@submodule

 

相关标签：

@main, @submodule, @example, @namespace, @for.

 @class  
复制代码 
/**
  * <b>Superclass</b> description.<br>This is a second line too.
  * 
  * @constructor
  * @class SuperWidget
  * @extends Widget
  * @namespace mywidget
  * @example
  *
  *     var bar;
  *
  */
复制代码

 

  

 类标签;

会扫描后面的@method, @property, @event, @attribute

如果是继承的话，加入@extends/@extensionfor

在@class中，想使用@example的话，必须加入@constructor

 

相关标签：

@constructor, @extends, @extensionfor, @for, @module, @namespace, @static, @uses.

 @method
复制代码 
/**
  * Overwritten method see {{#crossLink "mywidget.SuperWidget"}}
    {{/crossLink}}
  * also see {{#crossLink "mywidget.SuperWidget/myMethod"}}
     {{/crossLink}}
  * This is also a test
  * @method getTargets2
  * @example
  *
  *     var bar;
  *
  */
复制代码

 

 

 

 类方法标签；

描述方法

 经常有情况是method并不是在所在@class下，因此要指定是具体@class的话，请使用@for；

 参数说明使用@param

 返回值使用@return，如果返回的是该类（即this）对象的话使用@chainalbe

相关标签：

@chainable, @class, @constructor, @for, @param, @return, @static, @async, @protected, @private, @final.

 @method 例子2  
复制代码 
/**
  添加产品方法，注册到factory中
  @method add
  @param  {string} name   产品名称
  @param  {object} item   产品特性
  @param  {string} [parent] 父类名称，注册到factory中产品名称
  @return {object|klass}  返回创建的产品
  @example
      //一个widget工厂
      var widgetFactory = st.factory({
      //工厂名
      name : 'wdigetfactory',
      //工厂类型
      type: 'class',
      //基类对象  
      base : {} 
      });
　　　.......

 */
复制代码
   
 @property 
/**
  * Override Property
  * @property name2
  * @type String
  */

 

  

 类基础属性;

定义简单类型属性

 

相关标签：

@type, @for, @default, @@required, @optional, @readOnly, @static, @protected, @private, @final.

 @attribute   
/**
* Override Attribute
* @attribute focused3
* @required
*/
focused3 : {...},

 

    

类复杂属性;

 主要定义object这类复杂属性

 

相关标签：

@type, @for, @default, @@required, @optional, @readOnly, @static, @protected, @private, @final.

 @event  
复制代码 
/**
* Override Event
* @event init2
* @param {object} opt options
* @example
*         var a = '';
*/
 init2 : function(opt){
 }
复制代码

 

  

 类事件定义;

 与@method基本一致,作为事件分类区分

 

相关标签：

@chainable, @class, @constructor, @for, @param, @return, @static, @async, @protected, @private, @final, @bubbles.

 

次标签

 

标签名注释说明
 @submodule  
复制代码 
/**
 * Provides Y.JSON.parse method to accept JSON strings and return native
 * JavaScript objects.
 *
 * @module json
 * @submodule json-parse
 * @for JSON
 * @static
 */
复制代码

 

子模块；

作为@module的扩展，通常使用在很多@class不在一个@module的文件下的扩展

 @main  
复制代码 
/**
 * The JSON module adds support for serializing JavaScript ...
 *
 * @module json
 * @main json
 * @class JSON
 * @static
 */
复制代码

标示主模块；

主要作为定义目录使用；

例子在@class的同时定义了@module和main那么在生成后json和class JSON将共享同一注释信息

 @namespace  
复制代码 
/**
 * Subclass description.
 * 
 * @constructor
 * @namespace mywidget
 * @class SubWidget2
 * @extends Accordion
 */
复制代码

命名空间；

例子中，最终@class的路径会显示为mywidget.Subwidget2

 @extends  同上 继承标签；作为继承使用

 @extension

 @extensionfor

  略 扩展标签；同@extends相反，，对类进行扩展
 @constructor  同上

构造器标签；@class专用；

注意@class如果想使用@example必须要有@constructor

 @static   静态标示
 @final   常量，不可变标示
 @readOnly   只读
 @optional   可选
 @required   必选
 @param  
复制代码 
/**
 * 更新操作接口 **[接口方法]**
 * @method  update
 * @param  {object} op   参数；
 *    @param  {object} op.filter   过滤器
 *    @param  {object} op.data   更新数据
 *    @param  {object} op.success 成功之后执行的方法
 *    @param  {object} op.error   失败之后执行的方法
 * @return {object}      操作结果
 */
复制代码

参数标签；@method，@constructor的@class和@event可用

 @param可以设置子@param但最多为3级；子参数需要使用param.childparam的方式命名；

 每个@param可以设置多个类型如：@param {string|function};使用 "|"分割，中间不能有空格

 

 @return    返回值
 @chainable    当返回值为自己的类对象（即this）时使用
 @type  
复制代码 
/**
 * .........
 * @property useNativeParse
 * @type Boolean
 * @default true
 * @static
 */
复制代码
 类型标签；在@porperty和@attribute中使用
 @deault    默认值设置
 @for  
复制代码 
/**
 * Some method 'bar'
 * disconnected from
 * its class 'FarawayClass'...
 *
 * @method bar
 * @for FarawayClass
 */
复制代码 
/**
 * Some inner class 'foo'...
 *
 * @class foo
 * @for OuterClass
 */

 两种方式，但目标都是@class

1. 指明是哪个@class下的项，@method, @porperty, @attribute, @event使用

2. 设置@class的inner class，@class中使用

 @private    私有标识
 @protected    保护标识
 @async    异步方法标识
 @uses
复制代码 
/**
 * @class Panel
 * @constructor
 * @extends Widget
 * @uses WidgetAutohide
 * @uses WidgetButtons
...
 */
复制代码
混入mix便签；可以定义多个
 @requires 
/**
 * @module event-simulate
 * @requires event
 */
 模块依赖的标签；标示module使用了那些模块
 @since 
/**
 * @since 3.4.0
 */
 标示从哪个版本加入此功能
 @example
复制代码 
 /**
 * ui测试类； 
 * @class UI
 * @constructor
 * @content {string} type 内容
 * @example
 *         <html>
 *             <div id='container'>html render</div>
 *         </html>
 *         
 *         <script>
 *              var ui = new UI("UI测试"); 
 *         </script>
 */
复制代码

 

代码示例；两种模式：

1. js代码，直接写入js

2. html和js，使用<html></html>和<script></script>包括起来





转载：http://www.cnblogs.com/zhh8077/p/4011769.html

STM2263
关注
  • 0
    点赞
  • 踩
  • 0
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
专栏目录
yuidoc：YUI Javascript文档工具
03-03
裕多克 YUIJavaScript文档引擎。 概述 YUIDoc是一个应用程序，在构建时使用它来生成JavaScript代码的API文档。 YUIDoc是注释驱动的，并且支持多种JavaScript编码样式。 YUIDoc的输出是API文档，格式为一组HTML页面，包括有关方法，属性，自定义事件和JavaScript对象继承的信息。 YUIDoc最初是为YUI项目编写的； 它在生成的文件中使用YUI JavaScript和CSS，并支持常见的YUI约定，例如“自定义事件”。 也就是说，可以在非YUI代码上轻松高效地使用它。 安装 npm install -g yuidocjs 文献资料 贡献 请参阅 。 执照 根据Yahoo Inc. BSD许可，可以免费使用该软件。 有关许可证文本和版权信息，请参阅。
yuidoc-theme-blue:一个简单的主题，灵感来自yuidoc（npm版本）的蓝色
05-10
yuidoc-theme-blue 一个简单的主题，灵感来自yuidoc（npm版本）的蓝色 用法 安装yuidoc npm i -g yuidoc 指向主题目录 yuidoc ./src -t /path/to/yuidoc-theme-blue 笔记 如果您从这个分支安装yuidoc，那么您将有另一个标签 @exampleurl // points to a url that could be embeded in an iframe like this one http://jsfiddle.net/royriojas/ZuAhz/embedded/ 我需要该属性才能在方法和API上放一些示例，这些示例可能更像是我的API的实时示例。
YUIDoc语法参考
crystalNB的专栏
01-06 3285
原文：http://yui.github.com/yuidoc/syntax/index.html 概述： YUIDoc的语法对于使用过Javadoc, JSDoc, Doxygen或者其他文档生成工具的人来说应该非常熟悉。YUIDoc依赖诸如@param 或 @return等这类嵌入在注释模块中的标签, 它们以"/** "开始，并且以" */"结束。注释模块包含一些少量的标签来指明文档的特
推荐开源项目：YUIDoc——JavaScript文档生成引擎
gitblog_00095的博客
05-09 224
推荐开源项目：YUIDoc——JavaScript文档生成引擎 项目地址:https://gitcode.com/yui/yuidoc 1、项目介绍 YUIDoc 是一款由 Yahoo 开发的基于 Node.js 的 JavaScript 文档生成工具。它在构建期间运行，从代码注释中提取信息，生成一套完整的HTML页面形式的API文档，详细描述了方法、属性、自定义事件和继承等JavaScript对...
YUIDoc的使用方法小结
weixin_34228617的博客
07-30 93
>一.YUIDoc概述以及安装YUIDoc是为YUI　Library用来生成HTML版API文档的一系列工具集，文档的生成完全基于JavaDoc风格的代码注释规则。该工具是基于Python语言编写，并且使用了几个基于Python的扩展组件作为底层支持，如读写json对象、HTML模板管理以及源代码着色等等。所以在使用YUIDoc之前，请确保你的机器上已经安装了Python环境和YUIDoc所...
Javascript自动化文档工具：YUI Doc, JSDoc 3, JSDuck等比较
weixin_34007906的博客
03-05 325
最近随着写Node以及独立的CommonJS模块越来越多，我发现有一份好的文档不仅可以帮助自己在应用这些接口的时候不至于迷糊，而且对于共同开发的情况下，能够省去大量团队的交流和Debug的时间。 本文比较了5种较为主流的Javascript注释文档生成工具。需要指出的一点是，Javascript是一个极为灵活的语言，文档生成并不像Jav...
节点注释应用
02-18
5. 自动化工具：有一些自动化工具，如Dojo的dojoc或YUIDoc，可以扫描源代码中的JSDoc注释，并生成HTML文档。这些工具大大简化了文档的创建过程，让开发者能专注于编写高质量的代码。 6. IDE集成：许多集成开发环境...
前端开源库-swint-yuidoc
08-30
2. **编写 Yuidoc 注释**：在 Swint 任务的源代码中，按照 Yuidoc 的注释规范添加必要的文档描述。这包括对类、方法、参数等的描述，以 @tag 开头的特殊注释。 3. **生成文档**：在项目根目录下运行 `yuidoc` 命令...
前端开源库-gulp-yuidoc
08-29
通过将gulp-yuidoc集成到你的构建流程中，你可以自动化地从源代码注释中提取出清晰、结构化的文档。 Gulp是基于Node.js的自动化任务管理工具，允许开发者定义一系列任务来简化构建过程，如编译CSS、压缩JavaScript...
firedoc：基于YUIDoc的API Doc生成器
03-03
YUIDoc是注释驱动的，并且支持多种JavaScript编码样式。 YUIDoc的输出是API文档，格式为一组HTML页面，包括有关方法，属性，自定义事件和JavaScript对象继承的信息。 YUIDoc最初是为YUI项目编写的； 它在生成的文件...
使用YUIDoc创建js文档
帆酱的博客
03-18 484
什么是YUIDoc？ YUIDoc会根据你写的代码注释生成API文档。 YUIDoc是个NodeJS应用，能将你的JS代码中的注释生成HTML格式的API文档。事实上，不仅是JS，任何支持块注释的语言都能使用。 安装 要安装YUIDoc，首先要安装好NodeJS，然后使用npm -g install yuidocjs即可安装YUIDoc。 使用 在相应的目录下输入 yuidoc ....
JSDoc3、Doxx，YUIDoc简单介绍和对比
热门推荐
wts的专栏
02-13 1万+
这几天需要对开发的js文件生成doc，简单了解了一下，直接选用了JSDoc3，但JSDoc3默认生成的doc比较难看。于是就再看看其它的生成软件。 看了一篇写的不错的文章，对JSDoc、Doxx、YUIDoc、Docoo做了对比，地址：http://blog.fusioncharts.com/2013/12/jsdoc-vs-yuidoc-vs-doxx-vs-docco-choosing-a-
YuiDoc与JsDoc通用标签归纳汇总
jianyi7659的专栏
10-22 1898
 最近随着写Node以及独立的CommonJS模块越来越多，我发现有一份好的文档不仅可以帮助自己在应用这些接口的时候不至于迷糊，而且对于共同开发的情况下，能够省去大量团队的交流和Debug的时间。然而Javascript注释文档生成工具多大五六种，每一种的标签定义还不完全一样。 Javascript是一个极为灵活的语言，文档生成并不像Java那样具有绝对统一的规
SmartDoc(YUIDoc) 注释编写
weixin_30919919的博客
07-22 1245
上面介绍了JS文档和Demo生成工具SmartDoc，本篇开始介绍一下注释的编写。SmartDoc使用的是YUIDoc的引擎，所以的注释规则都一样，先简单介绍下YUIDoc的注释编写。 编写注释是一个很繁重的体力活，很多程序员都嫌麻烦不愿意做此事，但是在编写的过程，会让你注意到很多的细节和考虑一些没有想到的地方，会发现很多的问题和优化点。 为了比较好的提高效率，从code开始就应该...
Javascript API文档生成工具YUIDoc的安装
txp1993的专栏
08-22 1671
YUIDoc是基于Nodejs的可以将文档中的注释生成API文档的工具。它可以时时预览你写入的内容，支持自定义文档模版，生成的文档清晰易用，并且不局限于你所使用的语言，只要你的代码中按照YUIDoc规范的格式来写注释就可以生成想要的API文档，因此在各团队协作中用来作为统一的文档工具再合适不过了。
pillow_heif-0.17.0-pp39-pypy39_pp73-macosx_14_0_arm64.whl
07-27
基本介绍 名称与起源：Pillow，原名为PIL（Python Imaging Library），但PIL只支持Python 2版本。随着Python 3的普及，Pillow作为PIL的一个分支出现，兼容Python 3并提供更多的功能和改进。 主要功能：Pillow支持多种图像格式的打开、保存、显示以及基本的图像操作和处理，如裁剪、缩放、旋转、翻转、滤镜应用等。 跨平台性：Pillow库可以在不同的操作系统上运行，包括Windows、Linux和MacOS等。 主要功能模块 Pillow库包含多个功能模块，每个模块都提供了特定的图像处理功能。以下是一些常用的模块： Image：用于处理图像文件，提供打开、保存、调整大小、旋转、裁剪、滤镜等功能。 ImageDraw：提供在图像上绘制各种形状（如线条、矩形、圆形）和文本的功能。 ImageFont：用于加载和使用TrueType字体文件，以便在图像上绘制文本时设置字体样式、大小和颜色。 ImageFilter：提供各种滤镜效果，如模糊、锐化、边缘增强等，用于图像增强、特效处理和图像识别等应用。 ImageEnhance：用于调整图像的亮度、对比度、颜色饱和度等参数，使图像更加清晰、明亮或具有特定的调色效果。 高级功能 除了基本的图像处理功能外，Pillow还支持一些高级功能，如色彩空间转换、直方图均衡化等。这些功能可以帮助用户进行更复杂的图像处理和分析。
cykooz.resizer-3.0.0-cp310-cp310-macosx_11_0_arm64.whl
最新发布
07-27
python库，可以直接安装使用，再也不怕自己pip下载，出现等待超时的现象。欢迎下载使用，使用过程中如有使用问题，请及时与我沟通交流，帮你解决！ python库，可以直接安装使用，再也不怕自己pip下载，出现等待超时的现象。欢迎下载使用，使用过程中如有使用问题，请及时与我沟通交流，帮你解决！ python库，可以直接安装使用，再也不怕自己pip下载，出现等待超时的现象。欢迎下载使用，使用过程中如有使用问题，请及时与我沟通交流，帮你解决！ python库，可以直接安装使用，再也不怕自己pip下载，出现等待超时的现象。欢迎下载使用，使用过程中如有使用问题，请及时与我沟通交流，帮你解决！ python库，可以直接安装使用，再也不怕自己pip下载，出现等待超时的现象。欢迎下载使用，使用过程中如有使用问题，请及时与我沟通交流，帮你解决！
前端编码规范详解：通用规则与最佳实践
- 注释应解释代码的目的和决策背景，可链接到相关问题或解决方案，使用专门的工具如JSDoc或YUIDoc进行编写，有些工具能自动生成文档，鼓励开发者积极参与文档编写。 遵循这些前端编码规范，可以提升项目的可维护性...
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值