注释修改说明文档.md

Demo - 规范化的注释

在进行注释的添加或修改时，需要满足注释的规范性。

在Fluid项目中我们遵循Godoc以及Kubernetes生态的注释规范，下面将通过一个简单的示例演示注释修改的过程。

以下是一个不规范的注释：

/*
* this function prints "Hello"
* and returns the length of the given name.
* This is a demo function.
*/

func Hello(name string) int {
    fmt.Println("Hello")
    return len(name)
}

上述注释存在的问题为：

1. 不应使用/*<comments>*/作为注释，无论单行注释还是多行注释，永远使用//标识注释块

2. 注释与所注释的实体(e.g. func, struct等)不应当包含空行

3. 注释可以包含多句或多段，但整个注释的第一个单词需要为被注释实体的实体名。

更多注释规范请参考godoc

修改后如下所示：

// Hello prints "Hello" and returns the length of the given name.
// This is a demo function.
func Hello(name string) int {
    fmt.Printf("Hello, %s\n", name)
    return len(name)
}

一些官方的规范注释：

// Fprint formats using the default formats for its operands and writes to w.
// Spaces are added between operands when neither is a string.
// It returns the number of bytes written and any write error encountered.
func Fprint(w io.Writer, a ...interface{}) (n int, err error) {

// ListOptions contains options for limiting or filtering results.
// It's generally a subset of metav1.ListOptions, with support for
// pre-parsed selectors (since generally, selectors will be executed
// against the cache).
type ListOptions struct {

// Namespace represents the namespace to list for, or empty for
// non-namespaced objects, or to list across all namespaces.
Namespace string