# doc-ring

> Javascript文档生成工具

Latest version **0.0.6** (published 2015-03-27) · 0 weekly downloads

## Install

```sh
npm install doc-ring
pnpm add doc-ring
yarn add doc-ring
bun add doc-ring
```

## Health

**Score 10/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; low quality score; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.6 |
| Published | 2015-03-27 |
| First published | 2015-02-08 |
| Weekly downloads | 0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 7 |
| Known vulnerabilities | 0 (+10 in 2 direct dependencies) |
| Install scripts | no |
| Author | ZhangJianxiang |
| Maintainers | zjxwow |
| Keywords | javascript, doc, generator |

## Links

- npm: https://www.npmjs.com/package/doc-ring
- Repository: https://github.com/zjxwow/doc-ring
- Issues: https://github.com/zjxwow/doc-ring/issues
- npm.io page: https://npm.io/package/doc-ring

## Dependencies (7)

- [q](https://npm.io/package/q.md) 1.1.2
- [glob](https://npm.io/package/glob.md) 4.3.5
- [q-io](https://npm.io/package/q-io.md) 1.11.6
- [dgeni](https://npm.io/package/dgeni.md) 0.4.1
- [jsdoc](https://npm.io/package/jsdoc.md) 3.3.0-beta1
- [lodash](https://npm.io/package/lodash.md) 3.0.1
- [minimatch](https://npm.io/package/minimatch.md) 2.0.1

## Alternatives

- [@cantoo/pdf-lib](https://npm.io/package/@cantoo/pdf-lib.md) — 297.9K weekly downloads
- [datatables.net-buttons](https://npm.io/package/datatables.net-buttons.md) — 200.1K weekly downloads
- [@ckeditor/ckeditor5-export-pdf](https://npm.io/package/@ckeditor/ckeditor5-export-pdf.md) — 167.0K weekly downloads
- [scanbot-web-sdk](https://npm.io/package/scanbot-web-sdk.md) — 15.0K weekly downloads
- [@syncfusion/ej2-angular-pdfviewer](https://npm.io/package/@syncfusion/ej2-angular-pdfviewer.md) — 8.8K weekly downloads

## Recent versions

- 0.0.6 (latest) — 2015-03-27
- 0.0.5 — 2015-03-13
- 0.0.4 — 2015-03-09
- 0.0.3 — 2015-02-20
- 0.0.2 — 2015-02-13
- 0.0.1 — 2015-02-08

## README

这是一个专门用于生成Javascript文档的工具。只要注释文档遵循“[jsdoc3](http://usejsdoc.org/)”规范，就可以生成一份漂亮的文档。


# 安装

```
$ npm install doc-ring
```

# 配置项

* tutorials {Array} 教程、指南的路径，一般是README.md的markdown文件
* src {Array} 源文件路径
* dist {string} 输出文档的目录

# WIKI

* [jsdoc3命名路径](https://github.com/zjxwow/doc-ring/wiki/jsdoc3-Namepath)
* [jsdoc3文档规范具体说明](https://github.com/zjxwow/doc-ring/wiki/jsdoc3-Tags)

# Hello World

### 创建项目

新建一个目录取名“hello-doc”，安装好`doc-ring`和`gulp`：

```
$ npm install doc-ring gulp
```

在“hello-doc”根目录下创建“script”目录存放JS脚本，再新建一个“gulpfile.js”文件，现在目录结构是这样的：

```
/hello-doc
  /script
  gulpfile.js
```

### 书写代码和注释

在“script”目录下创建一个JS文件，取名为“foobar.js”，我们会以此文件作为源，读取其中的注释并生成文档，所以需要向它书写一些注释。

`doc-ring`遵循jsdoc3规范，作为演示只需要书写一个模块、一个属性和一个方法就好，这里使用AMD方式定义一个模块。

```js
/**
 * 一些描述{@link module:main/room}
 * @module foobar
 * @property {Object} lobal 全局对象
 */
define(function(){
  return {
    /**
     * @method
     * @description
     * 方法的一些描述
     * @param {string} pm 传入的参数说明
     */
    doSomething: function(pm){}
  };
})
```

### 构建和部署

回到“gulpfile.js”文件，书写如下代码：

```js
var docRing = require('./src');
var gulp = require('gulp');

gulp.task('default', function() {
  docRing({
    src: ['./script/**/*.js'],
    dist: './build'
  });
});
```

我们将输出文档定义在hello-doc目录下的“build”中。

现在在命令行中运行`gulp`即可输出文档：

```
$ gulp
```

现在根目录下应该会出现一个“build”目录，然后可以将它复制到apache服务器中运行，或将“build”目录建成一个静态文件服务器即可查看文档。

# 首页和教程文档

API文档有一个默认首页，用户也可以添加自定义首页。首页中可以放置对API库的综述等内容。

自定义的首页必须是一个markdown文件，只要将此文件路径包含在`src`配置项中即可。

```js
docRing({
  src: ['test/*.js', 'README.md'],
  dist: './build'
})
```

教程（tutorials）是针对一些特定主题的文档，例如angular的tutorial文档，教程可以有多个，每个教程文档必须是markdown格式的文件，有专门的`tutorials`配置项用于指定教程文件。

```js
docRing({
  tutorials: ['test/tutorials/*.md'],
  src: ['test/*.js'],
  dist: './build'
})
```

# 支持的标签

* [`@abstract`|`@virtual`](https://github.com/zjxwow/doc-ring/wiki/jsdoc3-Tags#abstract--virtual)
  定义抽象成员，必须被继承并实现。
* [`@access`](https://github.com/zjxwow/doc-ring/wiki/jsdoc3-Tags#access)
  成员可访问级别（private、public、protected）。
* [`@alias`](https://github.com/zjxwow/doc-ring/wiki/jsdoc3-tags#alias)
  符号的别名。
* [`@augments`|`@extends`](https://github.com/zjxwow/doc-ring/wiki/jsdoc3-tags#augmentsextends)
  如果一个类继承自一个父类，可使用此标签。
* [`@author`](https://github.com/zjxwow/doc-ring/wiki/jsdoc3-tags#author)
  标注作者名字。
* [`@callback`](https://github.com/zjxwow/doc-ring/wiki/jsdoc3-tags#callback)
  定义回调函数。
* [`@class`|`@constructor`](https://github.com/zjxwow/doc-ring/wiki/jsdoc3-tags#classconstructor)
  可以使用`new`关键字实例化的类。
* [`@classdesc`](https://github.com/zjxwow/doc-ring/wiki/jsdoc3-tags#classdesc)
  和类有关的描述文字。
* [`@deprecated`](https://github.com/zjxwow/doc-ring/wiki/jsdoc3-tags#deprecated)
  此符号已被废弃。
* [`@description`|`@desc`](https://github.com/zjxwow/doc-ring/wiki/jsdoc3-tags#descriptiondesc)
  符号的描述
* [`@event`](https://github.com/zjxwow/doc-ring/wiki/jsdoc3-tags#event)
  定义事件。
* [`@example`](https://github.com/zjxwow/doc-ring/wiki/jsdoc3-tags#example)
  为某个条目提供示例代码。
* [`@exports`](https://github.com/zjxwow/doc-ring/wiki/jsdoc3-tags#exports)
  某个成员会被JS模块暴露。
* [`@fires`|`@emits`](https://github.com/zjxwow/doc-ring/wiki/jsdoc3-tags#firesemits)
  某个方法可能会触发的事件。
* [`@function`|`@func`|`@method`](https://github.com/zjxwow/doc-ring/wiki/jsdoc3-tags#functionfuncmethod)
  定义一个函数或对象的方法。
* [`@global`](https://github.com/zjxwow/doc-ring/wiki/jsdoc3-tags#global)
  定义一个全局对象。
* [`@inner`](https://github.com/zjxwow/doc-ring/wiki/jsdoc3-tags#inner)
  定义内部成员。
* [`@instance`](https://github.com/zjxwow/doc-ring/wiki/jsdoc3-tags#instance)
  定义实例成员。
* [`@kind`](https://github.com/zjxwow/doc-ring/wiki/jsdoc3-tags#kind)
  符号的类型
* [`@lends`](https://github.com/zjxwow/doc-ring/wiki/jsdoc3-tags#lends)
  将对象字面量标记为某类的成员。
* [`@memberof`](https://github.com/zjxwow/doc-ring/wiki/jsdoc3-tags#memberof)
  某个符号隶属于另一个符号。
* [`@module`](https://github.com/zjxwow/doc-ring/wiki/jsdoc3-tags#module)
  定义一个JS模块。
* [`@name`](https://github.com/zjxwow/doc-ring/wiki/jsdoc3-tags#name)
  定义一个符号的名字。
* [`@override`](https://github.com/zjxwow/doc-ring/wiki/jsdoc3-tags#override)
  子类覆写了父类的成员。
* [`@param`|`@arg`|`argument`](https://github.com/zjxwow/doc-ring/wiki/jsdoc3-tags#paramargargument)
  函数的参数。
* [`@private`](https://github.com/zjxwow/doc-ring/wiki/jsdoc3-tags#private)
  定义私有成员。
* [`@property`](https://github.com/zjxwow/doc-ring/wiki/jsdoc3-tags#propertyprop)
  定义一个属性。
* [`@protected`](https://github.com/zjxwow/doc-ring/wiki/jsdoc3-tags#protected)
  定义某个符号的可访问性为“受保护”的。
* [`@public`](https://github.com/zjxwow/doc-ring/wiki/jsdoc3-tags#public)
  定义符号的可访问性为“公共”的。
* [`@readonly`](https://github.com/zjxwow/doc-ring/wiki/jsdoc3-tags#readonly)
  符号是只读的。
* [`@requires`](https://github.com/zjxwow/doc-ring/wiki/jsdoc3-tags#requires)
  标注依赖项。
* [`@returns`|`@return`](https://github.com/zjxwow/doc-ring/wiki/jsdoc3-tags#returnreturns)
  函数的返回值。
* [`@static`](https://github.com/zjxwow/doc-ring/wiki/jsdoc3-tags#static)
  某个符号是静态成员。
* [`@throws`](https://github.com/zjxwow/doc-ring/wiki/jsdoc3-tags#throws)
  函数会抛出的错误。
* [`@todo`](https://github.com/zjxwow/doc-ring/wiki/jsdoc3-tags#todo)
  列出待完成的任务。
* [`@type`](https://github.com/zjxwow/doc-ring/wiki/jsdoc3-tags#type)
  符号的数据类型。
* [`@typedef`](https://github.com/zjxwow/doc-ring/wiki/jsdoc3-tags#typedef)
  自定义类型。
* [`@version`](https://github.com/zjxwow/doc-ring/wiki/jsdoc3-tags#version)
  符号的版本。

---
_Source: https://npm.io/package/doc-ring · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._