Skip to content

Commit fada562

Browse files
committed
Add markdown lint + ci, and satisfy lint
1 parent 9a0bcb0 commit fada562

11 files changed

+152
-21
lines changed

.travis.yml

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
language: node_js
2+
node_js:
3+
- "node"

doc/handbook/Classes.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,7 @@ tom.move(34);
7979

8080
包含constructor函数的派生类必须调用`super()`,它会执行基类的构造方法。
8181

82-
```
82+
```plain
8383
Slithering...
8484
Sammy the Python moved 5m.
8585
Galloping...
@@ -141,7 +141,7 @@ class Rhino extends Animal {
141141

142142
class Employee {
143143
private name: string;
144-
constructor(theName: string) { this.name = theName; }
144+
constructor(theName: string) { this.name = theName; }
145145
}
146146

147147
let animal = new Animal("Goat");
@@ -245,7 +245,7 @@ class Employee {
245245
get fullName(): string {
246246
return this._fullName;
247247
}
248-
248+
249249
set fullName(newName: string) {
250250
if (passcode && passcode == "secret passcode") {
251251
this._fullName = newName;

doc/handbook/Functions.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -236,7 +236,7 @@ let deck = {
236236
return function() {
237237
let pickedCard = Math.floor(Math.random() * 52);
238238
let pickedSuit = Math.floor(pickedCard / 13);
239-
239+
240240
return {suit: this.suits[pickedSuit], card: pickedCard % 13};
241241
}
242242
}
@@ -267,7 +267,7 @@ let deck = {
267267
return () => {
268268
let pickedCard = Math.floor(Math.random() * 52);
269269
let pickedSuit = Math.floor(pickedCard / 13);
270-
270+
271271
return {suit: this.suits[pickedSuit], card: pickedCard % 13};
272272
}
273273
}

doc/handbook/Interfaces.md

+12-11
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,7 @@ printLabel(myObj);
4444
还有一点值得提的是,类型检查器不会去检查属性的顺序,只要相应的属性存在并且类型也是对的就可以。
4545

4646
# 可选属性
47+
4748
接口里的属性不全都是必需的。
4849
有些是只在某些条件下存在,或者根本不存在。
4950
可选属性在应用“option bags”模式时很常用,即给函数传入的参数对象中只有部分属性赋值了。
@@ -360,24 +361,24 @@ c.interval = 5.0;
360361
例:
361362

362363
```ts
363-
class Control {
364-
private state: any;
364+
class Control {
365+
private state: any;
365366
}
366367

367-
interface SelectableControl extends Control {
368-
select(): void;
368+
interface SelectableControl extends Control {
369+
select(): void;
369370
}
370371

371-
class Button extends Control {
372-
select() { }
372+
class Button extends Control {
373+
select() { }
373374
}
374-
class TextBox extends Control {
375-
select() { }
375+
class TextBox extends Control {
376+
select() { }
376377
}
377-
class Image extends Control {
378+
class Image extends Control {
378379
}
379-
class Location {
380-
select() { }
380+
class Location {
381+
select() { }
381382
}
382383
```
383384

doc/handbook/Type Compatibility.md

+3
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ TypeScript的结构性子类型是根据JavaScript代码的典型写法来设计
2929
TypeScript的类型系统允许一些在编译阶段无法否认其安全性的操作。当一个类型系统具此属性时,被当做是“不可靠”的。TypeScript允许这种不可靠行为的发生是经过仔细考虑的。通过这篇文章,我们会解释什么时候会发生这种情况和其有利的一面。
3030

3131
# 开始
32+
3233
TypeScript结构化类型系统的基本规则是,如果`x`要兼容`y`,那么`y`至少具有与`x`相同的属性。比如:
3334

3435
```ts
@@ -107,6 +108,7 @@ y = x; // Error because x() lacks a location property
107108
类型系统强制源函数的返回值类型必须是目标函数返回值类型的子类型。
108109

109110
## 函数参数双向协变
111+
110112
当比较函数参数类型时,只有当源函数参数能够赋值给目标函数或者反过来时才能赋值成功。
111113
这是不稳定的,因为调用者可能传入了一个具有更精确类型信息的函数,但是调用这个传入的函数的时候却使用了不是那么精确的类型信息。
112114
实际上,这极少会发生错误,并且能够实现很多JavaScript里的常见模式。例如:
@@ -134,6 +136,7 @@ listenEvent(EventType.Mouse, (e: number) => console.log(e));
134136
```
135137

136138
## 可选参数及剩余参数
139+
137140
比较函数兼容性的时候,可选参数与必须参数是可交换的。
138141
原类型上额外的可选参数并不会造成错误,目标类型的可选参数没有对应的参数也不是错误。
139142

doc/handbook/Typings for NPM Packages.md

+2-1
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
1-
TypeScript编译器处理nodejs模块名时使用的是[Node.js模块解析算法](https://nodejs.org/api/modules.html#modules_all_together)
1+
<!-- markdownlint-disable MD029 -->TypeScript编译器处理nodejs模块名时使用的是[Node.js模块解析算法](https://nodejs.org/api/modules.html#modules_all_together)。
22
TypeScript编译器可以同时加载与npm包绑在一起的类型信息。
33
编译通过下面的规则来查找`"foo"`模块的类型信息:
44

55
1. 尝试加载相应代码包目录下`package.json`文件(`node_modules/foo/`)。
6+
67
如果存在,从`"typings"`字段里读取类型文件的路径。比如,在下面的`package.json`里,编译器会认为类型文件位于`node_modules/foo/lib/foo.d.ts`
78

89
```JSON

doc/handbook/Variable Declarations.md

+1
Original file line numberDiff line numberDiff line change
@@ -234,6 +234,7 @@ console.log(e);
234234
a++; // illegal to use 'a' before it's declared;
235235
let a;
236236
```
237+
237238
注意一点,我们仍然可以在一个拥有块作用域变量被声明前*获取*它。
238239
只是我不能在变量声明前去调用那个函数。
239240
如果生成代码目标为ES2015,现代的运行时会抛出一个错误;然而,现今TypeScript是不会报错的。

doc/handbook/Writing Definition Files.md

+2
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
# 介绍
2+
23
当使用外部JavaScript库或新的宿主API时,你需要一个声明文件(.d.ts)定义程序库的shape。
34
这个手册包含了写.d.ts文件的高级概念,并带有一些例子,告诉你怎么去写一个声明文件。
45

@@ -84,6 +85,7 @@ declare let A: A_Static;
8485
```
8586

8687
这里的利弊如下:
88+
8789
* 标准方式可以使用extends来继承;分解的类不能。这可能会在未来版本的TypeScript里改变:是否允许任何的extends表达式
8890
* 都允许之后为类添加静态成员
8991
* 允许为分解的类再添加实例成员,标准版不允许

doc/handbook/tsconfig.json.md

+1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
## 概述
2+
23
如果一个目录下存在一个`tsconfig.json`文件,那么它意味着这个目录是TypeScript项目的根目录。
34
`tsconfig.json`文件中指定了用来编译这个项目的根文件和编译选项。
45
`tsconfig.json`从TypeScript 1.5开始支持。

lint.js

+117
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
var markdownlint = require("markdownlint");
2+
var glob = require("glob");
3+
var fs = require("fs");
4+
5+
var inputFiles = glob.sync("doc/handbook/**/*.md", { ignore: "node_modules/**/*" });
6+
var options = {
7+
files: inputFiles,
8+
config: {
9+
MD001: false, // Header levels should only increment by one level at a time
10+
MD002: false, // First header should be a h1 header
11+
MD003: false, // Header style
12+
MD004: { style: "asterisk" }, // Unordered list style
13+
MD005: true, // Inconsistent indentation for list items at the same level
14+
MD006: true, // Consider starting bulleted lists at the beginning of the line
15+
MD007: { indent: 4 }, // Unordered list indentation
16+
MD009: true, // Trailing spaces
17+
MD010: true, // Hard tabs
18+
MD011: true, // Reversed link syntax
19+
MD012: false, // Multiple consecutive blank lines
20+
MD013: false, // Line length
21+
MD014: false, // Dollar signs used before commands without showing output
22+
MD018: true, // No space after hash on atx style header
23+
MD019: true, // Multiple spaces after hash on atx style header
24+
MD020: false, // No space inside hashes on closed atx style header
25+
MD021: false, // Multiple spaces inside hashes on closed atx style header
26+
MD022: true, // Headers should be surrounded by blank lines
27+
MD023: true, // Headers must start at the beginning of the line
28+
MD024: false, // Multiple headers with the same content
29+
MD025: false, // Multiple top level headers in the same document
30+
MD026: { punctuation: ".,;:!?" }, // Trailing punctuation in header
31+
MD027: true, // Multiple spaces after blockquote symbol
32+
MD028: false, // Blank line inside blockquote
33+
MD029: { style: "ordered" }, // Ordered list item prefix
34+
MD030: true, // Spaces after list markers
35+
MD031: true, // Fenced code blocks should be surrounded by blank lines
36+
MD032: true, // Lists should be surrounded by blank lines
37+
MD033: false, // Inline HTML
38+
MD034: true, // Bare URL used
39+
MD035: false, // Horizontal rule style
40+
MD036: false, // Emphasis used instead of a header
41+
MD037: true, // Spaces inside emphasis markers
42+
MD038: false, // Spaces inside code span elements
43+
MD039: true, // Spaces inside link text
44+
MD040: true, // Fenced code blocks should have a language specified
45+
MD041: false, // First line in file should be a top level header
46+
}
47+
};
48+
49+
var result = markdownlint.sync(options);
50+
console.log(result.toString());
51+
52+
var exitCode = 0;
53+
Object.keys(result).forEach(function (file) {
54+
var fileResults = result[file];
55+
Object.keys(fileResults).forEach(function (rule) {
56+
var ruleResults = fileResults[rule];
57+
exitCode += ruleResults.length;
58+
});
59+
});
60+
61+
inputFiles.forEach(function(fileName) {
62+
var text = fs.readFileSync(fileName, "utf8")
63+
exitCode += checkForImproperlyIndentedFencedCodeBlocks(fileName, text);
64+
})
65+
66+
process.exit(exitCode);
67+
68+
/**
69+
* @param {string} fileName
70+
* @param {string} text
71+
*/
72+
function checkForImproperlyIndentedFencedCodeBlocks(fileName, text) {
73+
var lines = text.split(/\r?\n/g);
74+
var numErrors = 0;
75+
76+
for (var i = 0; i < lines.length; i++) {
77+
var line = lines[i];
78+
var codeBlockMatch = line.match(/^(\s*)```\S+/);
79+
80+
if (codeBlockMatch) {
81+
var startingColumn = codeBlockMatch[1].length;
82+
if (startingColumn === 0 || startingColumn === getCorrectStartingColumnForLine(lines, i)) {
83+
continue;
84+
}
85+
86+
numErrors++;
87+
console.log(fileName, ": ",
88+
i + 1, ": A fenced code block following a list item must be indented to the first non-whitespace character of the list item.")
89+
}
90+
}
91+
92+
return numErrors;
93+
}
94+
95+
/**
96+
* @param {string[]} line
97+
* @param {number} lineIndex
98+
*/
99+
function getCorrectStartingColumnForLine(lines, lineIndex) {
100+
for (var i = lineIndex - 1; i >= 0; i--) {
101+
var line = lines[i];
102+
103+
if (line.length === 0) {
104+
continue;
105+
}
106+
107+
var m;
108+
if (m = line.match(/^\s*([\*\-]|(\d+\.))\s*/)) {
109+
return m[0].length;
110+
}
111+
if (m = line.match(/^(\s*)/)) {
112+
return m[0].length;
113+
}
114+
}
115+
116+
return 0;
117+
}

package.json

+6-4
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
{
2-
"name": "TypeScript-Tool",
2+
"name": "typescript-handbook-cn",
33
"version": "1.0.0",
4-
"description": "TypeScript starter package",
4+
"description": "The TypeScript Handbook is a comprehensive guide to the TypeScript language",
55
"directories": {
66
"doc": "doc"
77
},
88
"scripts": {
9-
"test": " "
9+
"test": "node lint.js"
1010
},
1111
"repository": {
1212
"type": "git",
@@ -23,6 +23,8 @@
2323
"homepage": "https://github.com/zhongsp/TypeScript",
2424
"devDependencies": {
2525
"gulp": "^3.8.11",
26-
"gulp-typescript": "^2.6.0"
26+
"gulp-typescript": "^2.6.0",
27+
"glob": "^5.0.15",
28+
"markdownlint": "0.0.8"
2729
}
2830
}

0 commit comments

Comments
 (0)