Skip to content

Commit 745ea4d

Browse files
reyoungreyoung
authored
Merge pull request #11354 from reyoung/feature/polish_doc
Polish documentation
2 parents 4c3eb44 + 055df47 commit 745ea4d

File tree

15 files changed

+553
-261
lines changed

15 files changed

+553
-261
lines changed

‎paddle/fluid/operators/activation_op.cc

Lines changed: 17 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -271,18 +271,18 @@ class HardShrinkOpMaker : public framework::OpProtoAndCheckerMaker {
271271
void Make() override {
272272
AddInput("X", "Input of HardShrink operator");
273273
AddOutput("Out", "Output of HardShrink operator");
274-
AddAttr<float>("threshold", "The value of threshold for HardShrink")
274+
AddAttr<float>("threshold",
275+
"The value of threshold for HardShrink. [default: 0.5]")
275276
.SetDefault(0.5f);
276277
AddComment(R"DOC(
277-
HardShrink Activation Operator.
278+
:strong:`HardShrink activation operator`
278279
279-
$$
280-
out = \begin{cases}
281-
x, \text{if } x > \lambda \\
282-
x, \text{if } x < -\lambda \\
283-
0, \text{otherwise}
284-
\end{cases}
285-
$$
280+
.. math::
281+
out = \begin{cases}
282+
x, \text{if } x > \lambda \\
283+
x, \text{if } x < -\lambda \\
284+
0, \text{otherwise}
285+
\end{cases}
286286
287287
)DOC");
288288
}
@@ -394,18 +394,18 @@ class ThresholdedReluOpMaker : public framework::OpProtoAndCheckerMaker {
394394
void Make() override {
395395
AddInput("X", "Input of ThresholdedRelu operator");
396396
AddOutput("Out", "Output of ThresholdedRelu operator");
397-
AddAttr<float>("threshold", "The threshold location of activation")
397+
AddAttr<float>("threshold",
398+
"The threshold location of activation. [default 1.0].")
398399
.SetDefault(1.0f);
399400
AddComment(R"DOC(
400-
ThresholdedRelu Activation Operator.
401+
:strong:`ThresholdedRelu activation operator`
401402
402-
$$
403-
out = \begin{cases}
404-
x, \text{if } x > threshold \\
405-
0, \text{otherwise}
406-
\end{cases}
407-
$$
403+
.. math::
408404
405+
out = \begin{cases}
406+
x, \text{if } x > threshold \\
407+
0, \text{otherwise}
408+
\end{cases}
409409
)DOC");
410410
}
411411
};

‎paddle/fluid/operators/compare_op.cc

Lines changed: 15 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -23,30 +23,26 @@ class CompareOpProtoMaker : public framework::OpProtoAndCheckerMaker {
2323
public:
2424
void Make() override {
2525
OpComment comment;
26-
AddInput("X",
27-
string::Sprintf("(LoDTensor) the left hand operand of %s operator",
28-
comment.type));
29-
AddInput("Y", string::Sprintf(
30-
"(LoDTensor) the right hand operand of %s operator",
31-
comment.type));
26+
AddInput("X", string::Sprintf("the left hand operand of %s operator",
27+
comment.type));
28+
AddInput("Y", string::Sprintf("the right hand operand of %s operator",
29+
comment.type));
3230
AddAttr<bool>("force_cpu",
33-
"(bool, default false) Force fill output variable to cpu "
31+
"Force fill output variable to cpu "
3432
"memory. Otherwise, fill output variable to the running "
35-
"device")
36-
.SetDefault(false);
37-
AddOutput("Out", string::Sprintf(
38-
"(LoDTensor) n-dim bool tensor. Each element is %s",
39-
comment.equation));
40-
AddComment(string::Sprintf(R"DOC(%s Operator
41-
33+
"device [default true].")
34+
.SetDefault(true);
35+
AddOutput("Out", string::Sprintf("n-dim bool tensor. Each element is %s",
36+
comment.equation));
37+
AddComment(string::Sprintf(R"DOC(
4238
It operates element-wise on X and Y, and returns the Out. Each of them is a
4339
N-dim tensor. X and Y could be any type. The each element of the Out tensor is
44-
calculated by %s
40+
calculated by $%s$
4541
)DOC",
46-
comment.type, comment.equation));
47-
AddAttr<int>("axis",
48-
"(int, default -1). The start dimension index "
49-
"for broadcasting Y onto X.")
42+
comment.equation));
43+
AddAttr<int>(
44+
"axis",
45+
"The start dimension index for broadcasting Y onto X. [default -1]")
5046
.SetDefault(-1)
5147
.EqualGreaterThan(-1);
5248
}

‎paddle/fluid/operators/cumsum_op.cc

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -30,19 +30,19 @@ class CumOp : public framework::OperatorWithKernel {
3030
class CumsumOpMaker : public framework::OpProtoAndCheckerMaker {
3131
public:
3232
void Make() override {
33-
AddInput("X", "Input of Cumsum operator");
34-
AddOutput("Out", "Output of Cumsum operator");
33+
AddInput("X", "Input of cumsum operator");
34+
AddOutput("Out", "Output of cumsum operator");
3535
AddAttr<int>("axis",
36-
"(int, default -1). The dimenstion to accumulate along. "
37-
"-1 means the last dimenstion")
36+
"The dimenstion to accumulate along. -1 means the last "
37+
"dimenstion [default -1].")
3838
.SetDefault(-1)
3939
.EqualGreaterThan(-1);
4040
AddAttr<bool>("exclusive",
41-
"bool, default false). Whether to perform exclusive cumsum")
41+
"Whether to perform exclusive cumsum. [default false].")
4242
.SetDefault(false);
4343
AddAttr<bool>("reverse",
44-
"bool, default false). If true, the cumsum is performed in "
45-
"the reversed direction")
44+
"If true, the cumsum is performed in the reversed direction. "
45+
"[default false].")
4646
.SetDefault(false);
4747
AddComment(R"DOC(
4848
The cumulative sum of the elements along a given axis.

‎paddle/fluid/operators/layer_norm_op.cc

Lines changed: 17 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -62,47 +62,48 @@ class LayerNormOp : public framework::OperatorWithKernel {
6262
class LayerNormOpMaker : public framework::OpProtoAndCheckerMaker {
6363
public:
6464
void Make() override {
65-
AddInput("X", "(LoDTensor) The input tensor.");
65+
AddInput("X", "The input tensor.");
6666
AddInput("Scale",
67-
"(Tensor, optional) Scale is a 1-dimensional tensor of size "
67+
"(optional) Scale is a 1-dimensional tensor of size "
6868
"H(`begin_norm_axis` splits the tensor(`X`) to a matrix [N,H])."
6969
"It is applied to the output.")
7070
.AsDispensable();
7171
AddInput("Bias",
72-
"(Tensor, optional) Bias is a 1-dimensional tensor of size "
72+
"(optional) Bias is a 1-dimensional tensor of size "
7373
"H(`begin_norm_axis` splits the tensor(`X`) to a matrix [N,H])."
7474
"It is applied to the output.")
7575
.AsDispensable();
76-
AddOutput("Y", "(LoDTensor) Result after normalization.");
77-
AddOutput("Mean", "(Tensor) Mean of the current mini batch.")
78-
.AsIntermediate();
79-
AddOutput("Variance", "(Tensor) Variance of the current mini batch.")
76+
AddOutput("Y", "Result after normalization.");
77+
AddOutput("Mean", "Mean of the current mini batch.").AsIntermediate();
78+
AddOutput("Variance", "Variance of the current mini batch.")
8079
.AsIntermediate();
8180

8281
AddAttr<float>("epsilon",
83-
"(float, default 1e-5) Constant for "
84-
"numerical stability")
82+
"Constant for numerical stability [default 1e-5].")
8583
.SetDefault(1e-5)
8684
.AddCustomChecker([](const float &epsilon) {
8785
PADDLE_ENFORCE(epsilon >= 0.0f && epsilon <= 0.001f,
8886
"'epsilon' should be between 0.0 and 0.001.");
8987
});
9088
AddAttr<int>("begin_norm_axis",
91-
"(int default:1), the "
92-
"axis of `begin_norm_axis ... Rank(X) - 1` will be "
89+
"the axis of `begin_norm_axis ... Rank(X) - 1` will be "
9390
"normalized. `begin_norm_axis` splits the tensor(`X`) to a "
94-
"matrix [N,H].")
91+
"matrix [N,H]. [default 1].")
9592
.SetDefault(1)
9693
.AddCustomChecker([](const int &begin_norm_axis) {
9794
PADDLE_ENFORCE_GT(begin_norm_axis, 0,
9895
"'begin_norm_axis' should be greater than zero.");
9996
});
10097

10198
AddComment(R"DOC(
102-
Layer Normalization.
103-
Layer Norm has been implemented as discussed in the paper:
104-
https://arxiv.org/abs/1607.06450
105-
...
99+
Assume feature vectors exist on dimensions
100+
:attr:`begin_norm_axis ... rank(input)` and calculate the moment statistics
101+
along these dimensions for each feature vector :math:`a` with size
102+
:math:`H`, then normalize each feature vector using the corresponding
103+
statistics. After that, apply learnable gain and bias on the normalized
104+
tensor to scale and shift if :attr:`scale` and :attr:`shift` are set.
105+
106+
Refer to `Layer Normalization <https://arxiv.org/pdf/1607.06450v1.pdf>`_
106107
)DOC");
107108
}
108109
};

‎paddle/fluid/operators/multiplex_op.cc

Lines changed: 32 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -62,26 +62,46 @@ class MultiplexOp : public framework::OperatorWithKernel {
6262
class MultiplexOpMaker : public framework::OpProtoAndCheckerMaker {
6363
public:
6464
void Make() override {
65-
AddInput("Ids", "The index tensor of multiplex operator.");
66-
AddInput("X", "The candidate tensors of multiplex operator.")
65+
AddInput("Ids",
66+
"Tensor<int32>, index variable which is a 2-D tensor with shape "
67+
"[M, 1] where M is the batch size.");
68+
AddInput("X",
69+
"A list of variables to gather from. All variables have the same "
70+
"shape and the rank is at least 2.")
6771
.AsDuplicable();
6872
AddOutput("Out", "The output tensor of multiplex operator.");
6973
AddComment(R"DOC(
70-
Multiplex Operator.
71-
72-
Multiplex multiple tensors according to the index provided by the index tensor.
73-
74-
Ids: the index tensor.
75-
X[0 : N - 1]: the candidate tensors for output (N >= 2).
76-
For each index i from 0 to batchSize - 1, the output is the i-th row of the
74+
Referring to the given index variable, this layer selects rows from the
75+
input variables to construct a multiplex variable. Assuming that there are
76+
:math:`m` input variables and :math:`I_i` represents the i-th input
77+
variable and :math:`i` is in [0, :math:`m`). All input variables are
78+
tensors with same shape [:math:`d_0`, :math:`d_1`, ..., :math:`d_R`].
79+
Please note that rank of the input tensor should be at least 2. Each input
80+
variable will be treated as a 2-D matrix with shape [:math:`M`, :math:`N`]
81+
where :math:`M` for :math:`d_0` and :math:`N` for :math:`d_1` * :math:`d_2`
82+
* ... * :math:`d_R`. Let :math:`I_i[j]` be the j-th row of the i-th input
83+
variable. The given index variable should be a 2-D tensor with shape
84+
[:math:`M`, 1]. Let `ID[i]` be the i-th index value of the index variable.
85+
Then the output variable will be a tensor with shape [:math:`d_0`,
86+
:math:`d_1`, ..., :math:`d_R`]. If we treat the output tensor as a 2-D
87+
matrix with shape [:math:`M`, :math:`N`] and let :math:`O[i]` be the i-th
88+
row of the matrix, then `O[i]` is equal to :math:`I_{ID[i]}[i]`.
89+
90+
* Ids: the index tensor.
91+
92+
* X[0 : N - 1]: the candidate tensors for output (N >= 2).
93+
94+
* For each index i from 0 to batchSize - 1, the output is the i-th row of the
7795
the (Ids[i])-th tensor.
7896
7997
For i-th row of the output tensor:
8098
81-
$$y[i] = x_{k}[i]$$
99+
$$
100+
y[i] = x_{k}[i]
101+
$$
82102
83-
where `y` is the output tensor, `x_{k}` is the k-th input tensor,
84-
and `k = Ids[i]`.
103+
where $y$ is the output tensor, $x_{k}$ is the k-th input tensor,
104+
and $k = Ids[i]$.
85105
86106
)DOC");
87107
}

‎paddle/fluid/operators/reader/create_recordio_file_reader_op.cc

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -78,11 +78,15 @@ class CreateRecordIOReaderOp : public framework::OperatorBase {
7878
class CreateRecordIOReaderOpMaker : public FileReaderMakerBase {
7979
protected:
8080
void Apply() override {
81-
AddAttr<std::string>("filename", "The filename of record io reader");
81+
AddAttr<std::string>(
82+
"filename",
83+
"The filename of record file. This file will given to reader.");
8284
AddComment(R"DOC(
83-
CreateRecordIOReader Operator
85+
Open a recordio file and return the reader object. The returned reader object
86+
is thread-safe.
8487
85-
Create a reader from a record io file
88+
NOTE: This is a very low-level API. It is used for debugging data file or
89+
training. Please use `open_files` instead of this API for production usage.
8690
)DOC");
8791
}
8892
};

‎paddle/fluid/operators/reader/reader_op_registry.cc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ std::unique_ptr<framework::ReaderBase> CreateReaderByFileName(
5454
}
5555

5656
void FileReaderMakerBase::Make() {
57-
AddOutput("Out", "(ReaderHolder) The created random reader.").AsDuplicable();
57+
AddOutput("Out", "(ReaderHolder): The created random reader.").AsDuplicable();
5858
AddAttr<std::vector<int>>("shape_concat", "The concat of all data's shapes.");
5959
AddAttr<std::vector<int>>(
6060
"ranks",

‎paddle/fluid/operators/row_conv_op.cc

Lines changed: 19 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -78,23 +78,23 @@ class RowConvOpMaker : public framework::OpProtoAndCheckerMaker {
7878
public:
7979
void Make() override {
8080
AddInput("X",
81-
"(LoDTensor), the input(X) is a LodTensor, which supports "
81+
"the input(X) is a LodTensor, which supports "
8282
"variable time-length input sequences. The underlying tensor "
8383
"in this LoDTensor is a matrix with shape (T x N), where T "
8484
"is the total time steps in this mini-batch and N is the input "
8585
"data dimension.");
8686
AddInput("Filter",
87-
"(Tensor), the input(Filter) is a learnable parameter. It "
87+
"the input(Filter) is a learnable parameter. It "
8888
"is a 2-D tensor with shape (future_context x N), where, "
8989
"future_context is the future context length and N is the data "
9090
"dimension.");
9191
AddOutput("Out",
92-
"(LoDTensor), the output(Out) is a LodTensor, which supports "
92+
"the output(Out) is a LodTensor, which supports "
9393
"variable time-length input sequences. The underlying tensor "
9494
"in this LodTensor is a matrix with shape T x N, i.e., the "
9595
"same shape as X.");
9696
AddComment(R"DOC(
97-
Row-convolution Operator.
97+
:strong:`Row-convolution operator`
9898
9999
The row convolution is called lookahead convolution. This operator was
100100
introduced in the following paper for DeepSpeech2:
@@ -114,9 +114,23 @@ and a filter ($W$) of size $context \times d$,
114114
the output sequence is convolved as:
115115
116116
$$
117-
out_{i, :} = \sum_{j=i}^{i + context} in_{j,:} \dot W_{i-j, :}
117+
out_{i, :} = \\sum_{j=i}^{i + context} in_{j,:} \\cdot W_{i-j, :}
118118
$$
119119
120+
In the above equation:
121+
122+
* $Out_{i}$: The i-th row of output variable with shape [1, D].
123+
124+
* $\\tau$: Future context size.
125+
126+
* $X_{j}$: The j-th row of input variable with shape [1, D].
127+
128+
* $W_{i-j}$: The (i-j)-th row of parameters with shape [1, D].
129+
130+
More details about row_conv please refer to
131+
the design document
132+
https://github.com/PaddlePaddle/Paddle/issues/2228#issuecomment-303903645 .
133+
120134
)DOC");
121135
}
122136
};

‎paddle/fluid/operators/uniform_random_op.cc

Lines changed: 7 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -86,32 +86,24 @@ class UniformRandomOp : public framework::OperatorWithKernel {
8686
class UniformRandomOpMaker : public framework::OpProtoAndCheckerMaker {
8787
public:
8888
void Make() override {
89-
AddOutput("Out", "(Tensor) The output tensor of uniform random op");
89+
AddOutput("Out", "The output tensor of uniform random op");
9090
AddComment(R"DOC(
91-
Uniform random operator.
92-
9391
This operator initializes a tensor with random values sampled from a
94-
uniform distribution.
92+
uniform distribution. The random result is in set [min, max].
9593
9694
)DOC");
97-
AddAttr<std::vector<int>>("shape",
98-
"(vector<int>) The shape of the output tensor");
99-
AddAttr<float>("min",
100-
"(float, default -1.0) "
101-
"Minimum value of uniform random")
95+
AddAttr<std::vector<int>>("shape", "The shape of the output tensor");
96+
AddAttr<float>("min", "Minimum value of uniform random. [default -1.0].")
10297
.SetDefault(-1.0f);
103-
AddAttr<float>("max",
104-
"(float, default 1.0) "
105-
"Maximun value of uniform random")
98+
AddAttr<float>("max", "Maximun value of uniform random. [default 1.0].")
10699
.SetDefault(1.0f);
107100
AddAttr<int>("seed",
108-
"(int, default 0) "
109101
"Random seed used for generating samples. "
110102
"0 means use a seed generated by the system."
111103
"Note that if seed is not 0, this operator will always "
112-
"generate the same random numbers every time.")
104+
"generate the same random numbers every time. [default 0].")
113105
.SetDefault(0);
114-
AddAttr<int>("dtype", "(int, default 5(FP32)) Output tensor data type")
106+
AddAttr<int>("dtype", "Output tensor data type. [default 5(FP32)].")
115107
.SetDefault(framework::proto::VarType::FP32);
116108
}
117109
};

0 commit comments

Comments
 (0)