Small header changes and a Doxygen tweak to shape the C++ API a bit better. (tensorflow#5304)

yifeif · web-flow · commit b5943bd1bcaa · 2016-10-31T10:55:37.000-07:00
Change: 135747447 (cherry picked from commit 120c3f1)
diff --git a/tensorflow/core/framework/tensor.h b/tensorflow/core/framework/tensor.h
@@ -466,6 +466,8 @@ class Tensor {
 
 // Implementation details
 
+// START_SKIP_DOXYGEN
+
 // Interface to access the raw ref-counted data buffer.
 class TensorBuffer : public core::RefCounted {
  public:
@@ -659,6 +661,8 @@ inline Tensor& Tensor::operator=(Tensor&& other) {
   return *this;
 }
 
+// END_SKIP_DOXYGEN
+
 }  // namespace tensorflow
 
 #endif  // TENSORFLOW_CORE_FRAMEWORK_TENSOR_H_
diff --git a/tensorflow/core/framework/tensor_shape.h b/tensorflow/core/framework/tensor_shape.h
@@ -31,8 +31,19 @@ limitations under the License.
 
 namespace tensorflow {
 
+// START_SKIP_DOXYGEN
 class TensorShapeIter;  // Declared below
-
+// END_SKIP_DOXYGEN
+
+/// Represents the shape of a Tensor.
+///
+/// A tensor's shape is denoted by its number of dimensions and a size for each
+/// dimension.  For example, a Tensor represented by a 3 x 4 matrix would have
+/// a shape of 2-D, [3,4].
+///
+/// If you know the exact shape of your Tensor when you create the TensorShape
+/// object, you can specify it then, or you can create a TensorShape with
+/// zero dimensions and one element, and call AddDim() to add dimensions later.
 class TensorShape {
  public:
   /// \brief Construct a `TensorShape` from the provided sizes.
@@ -220,11 +231,13 @@ class TensorShape {
   int64 num_elements_;
 };
 
+/// Represents the value of one dimension in a TensorShape.
 struct TensorShapeDim {
   explicit TensorShapeDim(int64 s) : size(s) {}
   int64 size;
 };
 
+// START_SKIP_DOXYGEN
 class TensorShapeIter {
  public:
   TensorShapeIter(const TensorShape* shape, int d) : shape_(shape), d_(d) {}
@@ -243,6 +256,7 @@ class TensorShapeIter {
   const TensorShape* shape_;
   int d_;
 };
+// END_SKIP_DOXYGEN
 
 /// \brief Static helper routines for `TensorShape`. Includes a few common
 /// predicates on a tensor shape.
diff --git a/tensorflow/core/lib/core/status.h b/tensorflow/core/lib/core/status.h
@@ -25,6 +25,7 @@ limitations under the License.
 
 namespace tensorflow {
 
+/// Denotes success or failure of a call in Tensorflow.
 class Status {
  public:
   /// Create a success status.
diff --git a/tensorflow/core/platform/env.h b/tensorflow/core/platform/env.h
@@ -343,6 +343,7 @@ class EnvWrapper : public Env {
   Env* target_;
 };
 
+/// Represents a thread used to run a Tensorflow function.
 class Thread {
  public:
   Thread() {}
@@ -382,6 +383,8 @@ Status WriteBinaryProto(Env* env, const string& fname,
 Status ReadBinaryProto(Env* env, const string& fname,
                        ::tensorflow::protobuf::MessageLite* proto);
 
+// START_SKIP_DOXYGEN
+
 namespace register_file_system {
 
 template <typename Factory>
@@ -394,6 +397,8 @@ struct Register {
 
 }  // namespace register_file_system
 
+// END_SKIP_DOXYGEN
+
 }  // namespace tensorflow
 
 // Register a FileSystem implementation for a scheme. Files with names that have
diff --git a/tensorflow/core/platform/file_system.h b/tensorflow/core/platform/file_system.h
@@ -98,6 +98,8 @@ class FileSystem {
   virtual Status IsDirectory(const string& fname);
 };
 
+// START_SKIP_DOXYGEN
+
 #ifndef SWIG
 // Degenerate file system that provides no implementations.
 class NullFileSystem : public FileSystem {
@@ -160,6 +162,8 @@ class NullFileSystem : public FileSystem {
 };
 #endif
 
+// END_SKIP_DOXYGEN
+
 /// A file abstraction for randomly reading the contents of a file.
 class RandomAccessFile {
  public:
