Discuss about documentation of ops

[pkuyym]

Survey and conclusion

Here, I surveyed several popular dl frameworks including tensorflow, caffe2 and pytorch to check their ops' documentation. I select fully connected operator as a typical example.

Component

• Feature summarization: Summary function of this op (including equation and detailed description)
• Usage example: Tell how to use this op (refer PyTorch)
• Python api definition: Show definition of the python api
• Python wrapper location: Link to wrapper code
• Parameters description: Describe each parameters in python api
• CPP code location: Link to cpp source code
• Highlight note: Something should pay attention to
• Other

At least

• Feature summarization
• Python api definition
• Python wrapper location
• Parameter description

More

• Usage example
• Highlight note
• CPP code location
• Other

Documentation for PaddlePaddle Ops

• Python api definition
  [Python code snippet]
• Python wrapper location
  [URL]
• Feature summarization
  [Function summarization] [Equation and description] [Tips]
• Parameters description
  [Description] [Data type] [Shape]
• Usage example
  [Python code snippet]

An example

FC [python/paddle/v2/fluid/layers.py#fc]

fc(input,
   size,
   num_flatten_dims=1,
   param_attr=None,
   bias_attr=None,
   act=None,
   name=None,
   main_program=None,
   startup_program=None)

Applies linear transformation to the input data. The equation is:

$$Y = Act(W^T * X + b)$$

In the above equation:

• X: input value, a tensor with rank at least 2.
• W: weight, a 2D tensor with shape [M, N].
• b: bias, a float scalar.
• Act: function to apply non-linearity activation.

All the input variables of this function are passed in as local variables to the LayerHelper constructor.

Args

input (Variable): The input vaule, a tensor with rank at least 2.
size (int): The output size, an interge value.
num_flatten_dims (int): Column number of the input.
param_attr: The parameters/weights.
param_initializer: Initializer used to initialize transoformation weights. If None, XavierInitializer is used.
bias_attr: The bias parameter.
bias_initializer: Initializer used to initialize bias. If None, ConstantInitializer is used.
act (str): Activation type.
name (str): Name/alias of the layer.
main_program (Program): The main program calling this.
startup_program (Program): The startup program.

Returns

Variable: the tensor variable storing the transformation and non-linearity activation result

Exceptions

ValueError: if rank of input less than 2

Usage Examples

```python
data = fluid.layers.data(name='data', shape=[1], dtype='float32')
fc = fluid.layers.fc(input=data, size=10, act="tanh")
```

[shanyi15]

您好，此issue在近一个月内暂无更新，我们将于今天内关闭。若在关闭后您仍需跟进提问，可重新开启此问题，我们将在24小时内回复您。因关闭带来的不便我们深表歉意，请您谅解~感谢您对PaddlePaddle的支持!
Hello, this issue has not been updated in the past month. We will close it today for the sake of other user‘s experience. If you still need to follow up on this question after closing, please feel free to reopen it. In that case, we will get back to you within 24 hours. We apologize for the inconvenience caused by the closure and thank you so much for your support of PaddlePaddle Group!