Created by: lcy-seso

port layer 过程中发现目前已经添加 operator 的文档实在是太简陋了 @wangkuiyi :

• 比如 Paddle 里面 cross_entropy_op

  AddComment(R"DOC(
  OnehotCrossEntropy Operator.
              Y[i] = -log(X[i][j])
  )DOC");

  caffe2 的 doc：https://github.com/caffe2/caffe2/blob/master/caffe2/operators/cross_entropy_op.cc#L262

• 比如 Paddle 里面 mul_op

  AddComment(R"DOC(
  Two Element Mul Operator.
  The equation is: Out = X * Y
  )DOC");

  caffe2 的doc : https://github.com/caffe2/caffe2/blob/master/caffe2/operators/matmul_op.cc#L23

• 比如 Paddle 里面 softmax

   AddComment("Softmax Op");

  caffe2 的 doc ：https://github.com/caffe2/caffe2/blob/master/caffe2/operators/softmax_op.cc#L85

• 上面列举的doc未来会用来生成文档，但现在写得都极其简陋。

• 写完代码再集中补文档，按照过去的经历，难免出现应付差事。

• caffe2 代码中的doc未必每一个都写得很长，但至少都包含以下信息：

  1. 详细的描述 op 的功能，而不是“说了和没说一样”；
  2. 直接清晰地描述输入数据的类型、维度；

  以 mul_op 为例，下面是 caffe2 的doc：

  .SetDoc(R"DOC(
  Matrix multiplication Y = A * B, where A has size (M x K), B has size (K x N),
  and Y will have a size (M x N).
  )DOC")
      .Input(0, "A", "2D matrix of size (M x K)")
      .Input(1, "B", "2D matrix of size (K x N)")
      .Output(0, "Y", "2D matrix of size (M x N)")
      .Arg("trans_a", "Pass 1 to transpose A before multiplication")
      .Arg("trans_b", "Pass 1 to transpose B before multiplication");

  下面是 PaddlePaddle 代码中的doc：

  AddInput("X", "The first input of mul op");
  AddInput("Y", "The second input of mul op");
  AddOutput("Out", "The output of mul op");
  AddComment(R"DOC(
  Two Element Mul Operator.
  The equation is: Out = X * Y
  )DOC");

  相比之下， caffe2 的注释简洁，但是输入数据如何组织，应该满足什么样的要求都描述清楚了。而Paddle现在的文档可以说毫无信息量。

  mul_op 的注释本身已经非常简单，其它复杂 op 的文档目前是在是太简陋了。

附上 TensorFlow 的doc：

https://github.com/tensorflow/tensorflow/blob/96344140077298606c256eaf32b7e86a788d04bc/tensorflow/core/ops/nn_ops.cc#L94

可以看到，TF 和 caffe2 都解释了输入输出类型，维度要求，注意事项，但我们的文档中缺失这一部分。

• “The first input of ×” 这样的注释没有信息量。
• “Softmax Op" 这样的注释什么都没有说。

以上两种都应该极力避免。

需要一个统一的标准来撰写doc，强制遵守，而不是让大家按照自己的理解和发挥来写。