# 高效Dart: 文档

## 文档注释

### 要使用 /// 文档注释来对成员和类型建档。

Linter 规则： 文档注释的斜杠

### 推荐为公共API编写文档注释

Linter规则： 包 API 文档， 公有成员api文档

### 考虑使用一个库级文档注释

Unlike languages like Java where the class is the only unit of program organization, in Dart, a library is itself an entity that users work with directly, import, and think about. That makes the library directive a great place for documentation that introduces the reader to the main concepts and functionality provided within. Consider including:

• A single-sentence summary of what the library is for.
• Explanations of terminology used throughout the library.
• A couple of complete code samples that walk through using the API.
• Links to the most important or most commonly used classes and functions.
• Links to external references on the domain the library is concerned with.

You document a library by placing a doc comment right above the library directive at the start of the file. If the library doesn’t have a librarydirective, you can add one just to hang the doc comment off of it.

### 考虑为私有API编写文档注释

Doc comments aren’t just for external consumers of your library’s public API. They can also be helpful for understanding private members that are called from other parts of the library.

### 要以单句总结开启文档注释

Start your doc comment with a brief, user-centric description ending with a period. A sentence fragment is often sufficient. Provide just enough context for the reader to orient themselves and decide if they should keep reading or look elsewhere for the solution to their problem.

### 要将文档注释的第一句分隔为其自己的段落

Add a blank line after the first sentence to split it out into its own paragraph. If more than a single sentence of explanation is useful, put the rest in later paragraphs.

This helps you write a tight first sentence that summarizes the documentation. Also, tools like Dartdoc use the first paragraph as a short summary in places like lists of classes and members.

### 避免通过带有周边上下文的冗余

The reader of a class’s doc comment can clearly see the name of the class, what interfaces it implements, etc. When reading docs for a member, the signature is right there, and the enclosing class is obvious. None of that needs to be spelled out in the doc comment. Instead, focus on explaining what the reader doesn’t already know.

### 推荐以第三人称动词开启函数或方法注释

The doc comment should focus on what the code does.

### 推荐以名词词组开始的变量、getter或setter注释

The doc comment should stress what the property is. This is true even for getters which may do calculation or other work. What the caller cares about is the result of that work, not the work itself.

Avoid having a doc comment on both the setter and the getter, as DartDoc will show only one (the one on the getter.)

### 推荐以名词词组开始的库或类型注释

Doc comments for classes are often the most important documentation in your program. They describe the type’s invariants, establish the terminology it uses, and provide context to the other doc comments for the class’s members. A little extra effort here can make all of the other members simpler to document.

### CONSIDER including code samples in doc comments.

Humans are great at generalizing from examples, so even a single code sample makes an API easier to learn.

### DO use square brackets in doc comments to refer to in-scope identifiers.

Linter rule: comment_references

If you surround things like variable, method, or type names in square brackets, then dartdoc looks up the name and links to the relevant API docs. Parentheses are optional, but can make it clearer when you’re referring to a method or constructor.

To link to a member of a specific class, use the class name and member name, separated by a dot:

The dot syntax can also be used to refer to named constructors. For the unnamed constructor, put parentheses after the class name:

### DO use prose to explain parameters, return values, and exceptions.

Other languages use verbose tags and sections to describe what the parameters and returns of a method are.

The convention in Dart is to integrate that into the description of the method and highlight parameters using square brackets.

## Markdown

You are allowed to use most markdown formatting in your doc comments and dartdoc will process it accordingly using the markdown package.

There are tons of guides out there already to introduce you to Markdown. Its universal popularity is why we chose it. Here’s just a quick example to give you a flavor of what’s supported:

### 避免过渡使用markdown

When in doubt, format less. Formatting exists to illuminate your content, not replace it. Words are what matter.

### AVOID using HTML for formatting.

It may be useful to use it in rare cases for things like tables, but in almost all cases, if it’s too complex too express in Markdown, you’re better off not expressing it.

### PREFER backtick fences for code blocks.

Markdown has two ways to indicate a block of code: indenting the code four spaces on each line, or surrounding it in a pair of triple-backtick “fence” lines. The former syntax is brittle when used inside things like Markdown lists where indentation is already meaningful or when the code block itself contains indented code.

The backtick syntax avoids those indentation woes, lets you indicate the code’s language, and is consistent with using backticks for inline code.

## 编写

We think of ourselves as programmers, but most of the characters in a source file are intended primarily for humans to read. English is the language we code in to modify the brains of our coworkers. As for any programming language, it’s worth putting effort into improving your proficiency.

This section lists a few guidelines for our docs. You can learn more about best practices for technical writing, in general, from articles such asTechnical writing style.

### 推荐保持简洁

Be clear and precise, but also terse.

### AVOID abbreviations and acronyms unless they are obvious.

Many people don’t know what “i.e.”, “e.g.” and “et al.” mean. That acronym that you’re sure everyone in your field knows may not be as widely known as you think.

### 推荐使用this代替the来引用成员的实例

When documenting a member for a class, you often need to refer back to the object the member is being called on. Using “the” can be ambiguous.