Question

shape(squeeze(t)) ==> [2, 3]

The tile() op provides a good example in descriptive text:

For example, tiling `[a, b, c, d]` by `[2]` produces `[a b c d a b c d]`.

It is often helpful to show code samples in Python. Never put them in the C++
Ops file, and avoid putting them in the Python Ops doc. We recommend, if
possible, putting code samples in the
API guides .
Otherwise, add them to the module or class docstring where the Ops constructors
are called out.

Here's an example from the module docstring in api_guides/python/math_ops.md :

Segmentation

TensorFlow provides several operations that you can use to perform common
math computations on tensor segments.
...
In particular, a segmentation of a matrix tensor is a mapping of rows to
segments.

For example:

```python
c = tf.constant([[1,2,3,4], [-1,-2,-3,-4], [5,6,7,8]])
tf.segment_sum(c, tf.constant([0, 0, 1]))
  ==>  [[0 0 0 0]
        [5 6 7 8]]
```

Requirements, caveats, important notes

Examples:

This operation requires that: `-1-input.dims() <= dim <= input.dims()`

Note: This tensor will produce an error if evaluated. Its value must
be fed using the `feed_dict` optional argument to `Session.run()`,
`Tensor.eval()`, or `Operation.run()`.

Descriptions of arguments and output (returned) tensors.

Keep the descriptions brief and to the point. You should not have to explain how
the operation works in the argument sections.

Mention if the Op has strong constraints on the dimensions of the input or
output tensors. Remember that for C++ Ops, the type of the tensor is
automatically added as either as "A ..type.. Tensor" or "A Tensor with type in
{...list of types...}". In such cases, if the Op has a constraint on the
dimensions either add text such as "Must be 4-D" or start the description with
= (to prevent the tensor type to be added) and write something like "A 4-D
float tensor".

For example, here are two ways to document an image argument of a C++ op (note
the "=" sign):

image: Must be 4-D. The image to resize.

image:= A 4-D `float` tensor. The image to resize.

In the documentation, these will be rendered to markdown as

image: A `float` Tensor. Must be 4-D. The image to resize.

image: A 4-D `float` Tensor. The image to resize.

Optional arguments descriptions ("attrs")

The doc generator always describes the type for each attr and their default
value, if any. You cannot override that with an equal sign because the
description is very different in the C++ and Python generated docs.

Phrase any additional attr description so that it flows well after the type
and default value. The type and defaults are displayed first, and additional
descriptions follow afterwards. Therefore, complete sentences are best.

Here's an example from image_ops.cc :

REGISTER_OP("DecodePng")
    .Input("contents: string")
    .Attr("channels: int = 0")
    .Attr("dtype: {uint8, uint16} = DT_UINT8")
    .Output("image: dtype")
    .SetShapeFn(DecodeImageShapeFn)
    .Doc(R"doc(
Decode a PNG-encoded image to a uint8 or uint16 tensor.

The attr `channels` indicates the desired number of color channels for the
decoded image.

Accepted values are:

*   0: Use the number of channels in the PNG-encoded image.
*   1: output a grayscale image.
*   3: output an RGB image.
*   4: output an RGBA image.

If needed, the PNG-encoded image is transformed to match the requested
number of color channels.

contents: 0-D.  The PNG-encoded image.
channels: Number of color channels for the decoded image.
image: 3-D with shape `[height, width, channels]`.
)doc");

This generates the following Args section in
api_docs/python/tf/image/decode_png.md :

Args:

• `contents` : A Tensor of type string . 0-D. The PNG-encoded
  image.
• `channels` : An optional int . Defaults to 0 . Number of color
  channels for the decoded image.
• `dtype` : An optional tf.DType from: tf.uint8, tf.uint16 . Defaults to tf.uint 8 .
• `name` : A name for the operation (optional).

如果您发现本页面存在错误或可以改进，请 点击此处 帮助我们改进。