kudu-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From t...@apache.org
Subject [2/2] kudu git commit: [C++ client] doxygenized all C++ client API
Date Wed, 10 Aug 2016 17:50:21 GMT
[C++ client] doxygenized all C++ client API

Doxygenized the rest of header files distributed along with
Kudu C++ client bundle.  The client.h file was already doxygenized.

Change-Id: Id0f82a6c8a500a892bc1daff8444e91191dab3af
Reviewed-on: http://gerrit.cloudera.org:8080/3840
Reviewed-by: Adar Dembo <adar@cloudera.com>
Tested-by: Kudu Jenkins


Project: http://git-wip-us.apache.org/repos/asf/kudu/repo
Commit: http://git-wip-us.apache.org/repos/asf/kudu/commit/88fe33c9
Tree: http://git-wip-us.apache.org/repos/asf/kudu/tree/88fe33c9
Diff: http://git-wip-us.apache.org/repos/asf/kudu/diff/88fe33c9

Branch: refs/heads/master
Commit: 88fe33c99c8f69584334e83506bf710d885f6957
Parents: 1dbfb75
Author: Alexey Serbin <aserbin@cloudera.com>
Authored: Mon Aug 1 21:16:49 2016 -0700
Committer: Todd Lipcon <todd@apache.org>
Committed: Wed Aug 10 17:45:56 2016 +0000

----------------------------------------------------------------------
 src/kudu/client/callbacks.h        |  71 ++++++-
 src/kudu/client/client.h           |  17 +-
 src/kudu/client/resource_metrics.h |  19 +-
 src/kudu/client/row_result.h       |   6 +-
 src/kudu/client/scan_batch.h       | 235 +++++++++++++++------
 src/kudu/client/scan_predicate.h   |  12 +-
 src/kudu/client/schema.h           | 359 +++++++++++++++++++++++---------
 src/kudu/client/shared_ptr.h       |  28 +--
 src/kudu/client/stubs.h            |  19 ++
 src/kudu/client/value.h            |  29 ++-
 src/kudu/client/write_op.h         | 107 +++++++---
 src/kudu/common/partial_row.h      | 317 +++++++++++++++++++++++-----
 src/kudu/util/monotime.h           | 167 ++++++++++++---
 src/kudu/util/slice.h              | 195 +++++++++++++----
 src/kudu/util/status.h             | 174 ++++++++++------
 15 files changed, 1323 insertions(+), 432 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/kudu/blob/88fe33c9/src/kudu/client/callbacks.h
----------------------------------------------------------------------
diff --git a/src/kudu/client/callbacks.h b/src/kudu/client/callbacks.h
index 5c65d3b..f2b1c09 100644
--- a/src/kudu/client/callbacks.h
+++ b/src/kudu/client/callbacks.h
@@ -31,7 +31,8 @@ class Status;
 
 namespace client {
 
-// All possible log levels.
+
+/// @brief All possible log levels.
 enum KuduLogSeverity {
   SEVERITY_INFO,
   SEVERITY_WARNING,
@@ -39,7 +40,7 @@ enum KuduLogSeverity {
   SEVERITY_FATAL
 };
 
-// Interface for all logging callbacks.
+/// @brief The interface for all logging callbacks.
 class KUDU_EXPORT KuduLoggingCallback {
  public:
   KuduLoggingCallback() {
@@ -48,7 +49,22 @@ class KUDU_EXPORT KuduLoggingCallback {
   virtual ~KuduLoggingCallback() {
   }
 
-  // 'message' is NOT terminated with an endline.
+  /// Log the message.
+  ///
+  /// @note The @c message is NOT terminated with an endline.
+  ///
+  /// @param [in] severity
+  ///   Severity of the log message.
+  /// @param [in] filename
+  ///   The name of the source file the message is originated from.
+  /// @param [in] line_number
+  ///   The line of the source file the message is originated from.
+  /// @param [in] time
+  ///   The absolute time when the log event was generated.
+  /// @param [in] message
+  ///   The message to log. It's not terminated with an endline.
+  /// @param [in] message_len
+  ///   Number of characters in the @c message.
   virtual void Run(KuduLogSeverity severity,
                    const char* filename,
                    int line_number,
@@ -60,10 +76,11 @@ class KUDU_EXPORT KuduLoggingCallback {
   DISALLOW_COPY_AND_ASSIGN(KuduLoggingCallback);
 };
 
-// Logging callback that invokes a member function pointer.
+/// @brief The logging callback that invokes a member function of an object.
 template <typename T>
 class KUDU_EXPORT KuduLoggingMemberCallback : public KuduLoggingCallback {
  public:
+  /// @brief A handy typedef for the member function with appropriate signature.
   typedef void (T::*MemberType)(
       KuduLogSeverity severity,
       const char* filename,
@@ -72,11 +89,18 @@ class KUDU_EXPORT KuduLoggingMemberCallback : public KuduLoggingCallback {
       const char* message,
       size_t message_len);
 
+  /// Build an instance of KuduLoggingMemberCallback.
+  ///
+  /// @param [in] object
+  ///   A pointer to the object.
+  /// @param [in] member
+  ///   A pointer to the member function of the @c object to invoke.
   KuduLoggingMemberCallback(T* object, MemberType member)
     : object_(object),
       member_(member) {
   }
 
+  /// @copydoc KuduLoggingCallback::Run()
   virtual void Run(KuduLogSeverity severity,
                    const char* filename,
                    int line_number,
@@ -92,10 +116,12 @@ class KUDU_EXPORT KuduLoggingMemberCallback : public KuduLoggingCallback {
   MemberType member_;
 };
 
-// Logging callback that invokes a function pointer with a single argument.
+/// @brief The logging callback that invokes a function by pointer
+///   with a single argument.
 template <typename T>
 class KUDU_EXPORT KuduLoggingFunctionCallback : public KuduLoggingCallback {
  public:
+  /// @brief A handy typedef for the function with appropriate signature.
   typedef void (*FunctionType)(T arg,
       KuduLogSeverity severity,
       const char* filename,
@@ -104,11 +130,18 @@ class KUDU_EXPORT KuduLoggingFunctionCallback : public KuduLoggingCallback {
       const char* message,
       size_t message_len);
 
+  /// Build an instance of KuduLoggingFunctionCallback.
+  ///
+  /// @param [in] function
+  ///   A pointer to the logging function to invoke with the @c arg argument.
+  /// @param [in] arg
+  ///   An argument for the function invocation.
   KuduLoggingFunctionCallback(FunctionType function, T arg)
     : function_(function),
       arg_(arg) {
   }
 
+  /// @copydoc KuduLoggingCallback::Run()
   virtual void Run(KuduLogSeverity severity,
                    const char* filename,
                    int line_number,
@@ -124,7 +157,7 @@ class KUDU_EXPORT KuduLoggingFunctionCallback : public KuduLoggingCallback {
   T arg_;
 };
 
-// Interface for all status callbacks.
+/// @brief The interface for all status callbacks.
 class KUDU_EXPORT KuduStatusCallback {
  public:
   KuduStatusCallback() {
@@ -133,23 +166,35 @@ class KUDU_EXPORT KuduStatusCallback {
   virtual ~KuduStatusCallback() {
   }
 
+  /// Notify/report on the status.
+  ///
+  /// @param [in] s
+  ///   The status to report.
   virtual void Run(const Status& s) = 0;
 
  private:
   DISALLOW_COPY_AND_ASSIGN(KuduStatusCallback);
 };
 
-// Status callback that invokes a member function pointer.
+/// @brief The status callback that invokes a member function of an object.
 template <typename T>
 class KUDU_EXPORT KuduStatusMemberCallback : public KuduStatusCallback {
  public:
+  /// @brief A handy typedef for the member with appropriate signature.
   typedef void (T::*MemberType)(const Status& s);
 
+  /// Build an instance of the KuduStatusMemberCallback class.
+  ///
+  /// @param [in] object
+  ///   A pointer to the object.
+  /// @param [in] member
+  ///   A pointer to the member function of the @c object to invoke.
   KuduStatusMemberCallback(T* object, MemberType member)
     : object_(object),
       member_(member) {
   }
 
+  /// @copydoc KuduStatusCallback::Run()
   virtual void Run(const Status& s) OVERRIDE {
     (object_->*member_)(s);
   }
@@ -159,17 +204,27 @@ class KUDU_EXPORT KuduStatusMemberCallback : public KuduStatusCallback {
   MemberType member_;
 };
 
-// Status callback that invokes a function pointer with a single argument.
+/// @brief The status callback that invokes a function by pointer
+///   with a single argument.
 template <typename T>
 class KUDU_EXPORT KuduStatusFunctionCallback : public KuduStatusCallback {
  public:
+  /// @brief A handy typedef for the function with appropriate signature.
   typedef void (*FunctionType)(T arg, const Status& s);
 
+  /// Build an instance of KuduStatusFunctionCallback.
+  ///
+  /// @param [in] function
+  ///   A pointer to the status report function to invoke
+  ///   with the @c arg argument.
+  /// @param [in] arg
+  ///   An argument for the function invocation.
   KuduStatusFunctionCallback(FunctionType function, T arg)
     : function_(function),
       arg_(arg) {
   }
 
+  /// @copydoc KuduStatusCallback::Run()
   virtual void Run(const Status& s) OVERRIDE {
     function_(arg_, s);
   }

http://git-wip-us.apache.org/repos/asf/kudu/blob/88fe33c9/src/kudu/client/client.h
----------------------------------------------------------------------
diff --git a/src/kudu/client/client.h b/src/kudu/client/client.h
index 625ff3e..44843a3 100644
--- a/src/kudu/client/client.h
+++ b/src/kudu/client/client.h
@@ -303,10 +303,10 @@ class KUDU_EXPORT KuduClient : public sp::enable_shared_from_this<KuduClient> {
   /// @return Operation status.
   Status ListTabletServers(std::vector<KuduTabletServer*>* tablet_servers);
 
-  /// List only those tables whose names pass a substring match on 'filter'.
+  /// List only those tables whose names pass a substring match on @c filter.
   ///
   /// @param [out] tables
-  ///   Result tables 'tables' is appended to only on success.
+  ///   The placeholder for the result. Appended only on success.
   /// @param [in] filter
   ///   Substring filter to use; empty sub-string filter matches all tables.
   /// @return Status object for the operation.
@@ -584,7 +584,7 @@ class KUDU_EXPORT KuduTableCreator {
   KuduTableCreator& wait(bool wait);
 
   /// Create a table in accordance with parameters currently set for the
-  /// KuduTableCreator instance.  Once created, the table handle
+  /// KuduTableCreator instance. Once created, the table handle
   /// can be obtained using KuduClient::OpenTable() method.
   ///
   /// @pre The following methods of the KuduTableCreator must be called
@@ -592,9 +592,10 @@ class KUDU_EXPORT KuduTableCreator {
   ///     @li table_name()
   ///     @li schema()
   ///
-  /// @return Result status of the @c{CREATE TABLE} operation. The return value
-  ///   may indicate an error in the create table operation, or a misuse
-  ///   of the builder. In the latter case, only the last error is returned.
+  /// @return Result status of the <tt>CREATE TABLE</tt> operation.
+  ///   The return value may indicate an error in the create table operation,
+  ///   or a misuse of the builder. In the latter case, only the last error
+  ///   is returned.
   Status Create();
 
  private:
@@ -677,7 +678,7 @@ class KUDU_EXPORT KuduTable : public sp::enable_shared_from_this<KuduTable> {
   /// @param [in] col_name
   ///   Name of column to use for comparison.
   /// @param [in] op
-  ///   Comparision operation to use.
+  ///   Comparison operator to use.
   /// @param [in] value
   ///   The type of the value must correspond to the type of the column
   ///   to which the predicate is to be applied. For example,
@@ -696,7 +697,7 @@ class KUDU_EXPORT KuduTable : public sp::enable_shared_from_this<KuduTable> {
                                         KuduPredicate::ComparisonOp op,
                                         KuduValue* value);
 
-  /// @return The KuduClient object associated with the table.  The caller
+  /// @return The KuduClient object associated with the table. The caller
   ///   should not free the returned pointer.
   KuduClient* client() const;
 

http://git-wip-us.apache.org/repos/asf/kudu/blob/88fe33c9/src/kudu/client/resource_metrics.h
----------------------------------------------------------------------
diff --git a/src/kudu/client/resource_metrics.h b/src/kudu/client/resource_metrics.h
index d31edaf..feab053 100644
--- a/src/kudu/client/resource_metrics.h
+++ b/src/kudu/client/resource_metrics.h
@@ -26,20 +26,31 @@
 namespace kudu {
 namespace client {
 
+/// @brief A generic catalog of simple metrics.
 class KUDU_EXPORT ResourceMetrics {
  public:
   ResourceMetrics();
 
   ~ResourceMetrics();
 
-  // Return a map that contains all metrics, its key is the metric name
-  // and its value is corresponding metric count.
+  /// @return A map that contains all metrics, its key is the metric name
+  ///   and its value is corresponding metric count.
   std::map<std::string, int64_t> Get() const;
 
-  // Increment the given metric.
+  /// Increment/decrement the given metric.
+  ///
+  /// @param [in] name
+  ///   The name of the metric.
+  /// @param [in] amount
+  ///   The amount to increment the metric
+  ///   (negative @c amount corresponds to decrementing the metric).
   void Increment(const std::string& name, int64_t amount);
 
-  // Return the metric's current count.
+  /// Get current count for the specified metric.
+  ///
+  /// @param [in] name
+  ///   Name of the metric in question.
+  /// @return The metric's current count.
   int64_t GetMetric(const std::string& name) const;
 
  private:

http://git-wip-us.apache.org/repos/asf/kudu/blob/88fe33c9/src/kudu/client/row_result.h
----------------------------------------------------------------------
diff --git a/src/kudu/client/row_result.h b/src/kudu/client/row_result.h
index f1f29ee..f28b28a 100644
--- a/src/kudu/client/row_result.h
+++ b/src/kudu/client/row_result.h
@@ -22,9 +22,9 @@
 namespace kudu {
 namespace client {
 
-// DEPRECATED: Kudu 0.7.0 renamed KuduRowResult to KuduScanBatch::RowPtr.
-// The newer name is clearer that the row result's lifetime is tied to the
-// lifetime of a batch.
+/// @deprecated Kudu 0.7.0 renamed KuduRowResult to KuduScanBatch::RowPtr.
+///   The newer name is clearer that the row result's lifetime is tied to the
+///   lifetime of a batch.
 typedef KuduScanBatch::RowPtr KuduRowResult;
 
 } // namespace client

http://git-wip-us.apache.org/repos/asf/kudu/blob/88fe33c9/src/kudu/client/scan_batch.h
----------------------------------------------------------------------
diff --git a/src/kudu/client/scan_batch.h b/src/kudu/client/scan_batch.h
index 7808905..f3b0ea0 100644
--- a/src/kudu/client/scan_batch.h
+++ b/src/kudu/client/scan_batch.h
@@ -39,56 +39,81 @@ class TsAdminClient;
 namespace client {
 class KuduSchema;
 
-// A batch of zero or more rows returned from a KuduScanner.
-//
-// With C++11, you can iterate over the rows in the batch using a
-// range-foreach loop:
-//
-//   for (KuduScanBatch::RowPtr row : batch) {
-//     ... row.GetInt(1, ...)
-//     ...
-//   }
-//
-// In C++03, you'll need to use a regular for loop:
-//
-//   for (KuduScanBatch::const_iterator it = batch.begin(), it != batch.end();
-//        ++i) {
-//     KuduScanBatch::RowPtr row(*it);
-//     ...
-//   }
-//
-//   or
-//
-//   for (int i = 0, num_rows = batch.NumRows();
-//        i < num_rows;
-//        i++) {
-//     KuduScanBatch::RowPtr row = batch.Row(i);
-//     ...
-//   }
-//
-// Note that, in the above example, NumRows() is only called once at the
-// beginning of the loop to avoid extra calls to the non-inlined method.
+/// @brief A batch of zero or more rows returned by a scan operation.
+///
+/// Every call to KuduScanner::NextBatch() returns a batch of zero or more rows.
+/// You can iterate over the rows in the batch using:
+///
+/// range-foreach loop (C++11):
+/// @code
+///   for (KuduScanBatch::RowPtr row : batch) {
+///     ... row.GetInt(1, ...)
+///     ...
+///   }
+/// @endcode
+///
+/// regular for loop (C++03):
+/// @code
+///   for (KuduScanBatch::const_iterator it = batch.begin(), it != batch.end();
+///        ++i) {
+///     KuduScanBatch::RowPtr row(*it);
+///     ...
+///   }
+/// @endcode
+/// or
+/// @code
+///   for (int i = 0, num_rows = batch.NumRows();
+///        i < num_rows;
+///        i++) {
+///     KuduScanBatch::RowPtr row = batch.Row(i);
+///     ...
+///   }
+/// @endcode
+///
+/// @note In the above example, NumRows() is only called once at the
+///   beginning of the loop to avoid extra calls to the non-inlined method.
 class KUDU_EXPORT KuduScanBatch {
  public:
+  /// @brief A single row result from a scan.
+  ///
+  /// @note This object acts as a pointer into a KuduScanBatch, and therefore
+  ///   is valid only as long as the batch it was constructed from.
   class RowPtr;
+
+  /// @brief C++ forward iterator over the rows in a KuduScanBatch.
+  ///
+  /// This iterator yields KuduScanBatch::RowPtr objects which point inside
+  /// the row batch itself. Thus, the iterator and any objects obtained from it
+  /// are invalidated if the KuduScanBatch is destroyed or used
+  /// for a new NextBatch() call.
   class const_iterator;
+
+  /// A handy typedef for the RowPtr.
   typedef RowPtr value_type;
 
   KuduScanBatch();
   ~KuduScanBatch();
 
-  // Return the number of rows in this batch.
+  /// @return The number of rows in this batch.
   int NumRows() const;
 
-  // Return a reference to one of the rows in this batch.
-  // The returned object is only valid for as long as this KuduScanBatch.
+  /// Get a row at the specified index.
+  ///
+  /// @param [in] idx
+  ///   The index of the row to return.
+  /// @return A reference to one of the rows in this batch.
+  ///   The returned object is only valid for as long as this KuduScanBatch
+  ///   object is valid.
   KuduScanBatch::RowPtr Row(int idx) const;
 
+  /// @return Forward iterator to the start of the rows in the batch.
   const_iterator begin() const;
+  /// @return Forward iterator to the end of the rows in the batch.
   const_iterator end() const;
 
-  // Returns the projection schema for this batch.
-  // All KuduScanBatch::RowPtr returned by this batch are guaranteed to have this schema.
+  /// @return The projection schema for this batch.
+  ///   All KuduScanBatch::RowPtr returned by this batch are guaranteed
+  ///   to have this schema.
   const KuduSchema* projection_schema() const;
 
  private:
@@ -100,21 +125,35 @@ class KUDU_EXPORT KuduScanBatch {
   DISALLOW_COPY_AND_ASSIGN(KuduScanBatch);
 };
 
-// A single row result from a scan. Note that this object acts as a pointer into
-// a KuduScanBatch, and therefore is valid only as long as the batch it was constructed
-// from.
 class KUDU_EXPORT KuduScanBatch::RowPtr {
  public:
-  // Construct an invalid RowPtr. Before use, you must assign
-  // a properly-initialized value.
+  /// Construct an invalid RowPtr. Before use, you must assign
+  /// a properly-initialized value.
   RowPtr() : schema_(NULL), row_data_(NULL) {}
 
+  /// @param [in] col_name
+  ///   Name of the column.
+  /// @return @c true iff the specified column of the row has @c NULL value.
   bool IsNull(const Slice& col_name) const;
+
+  /// @param [in] col_idx
+  ///   Index of the column.
+  /// @return @c true iff the specified column of the row has @c NULL value.
   bool IsNull(int col_idx) const;
 
-  // These getters return a bad Status if the type does not match,
-  // the value is unset, or the value is NULL. Otherwise they return
-  // the current set value in *val.
+  /// @name Getters for integral type columns by column name.
+  ///
+  /// @param [in] col_name
+  ///   The name of the target column.
+  /// @param [out] val
+  ///   Placeholder for the result value.
+  /// @return Operation result status. Return a bad Status if at least one
+  ///   of the following is @c true:
+  ///     @li The type does not match.
+  ///     @li The value is unset.
+  ///     @li The value is @c NULL.
+  ///
+  ///@{
   Status GetBool(const Slice& col_name, bool* val) const WARN_UNUSED_RESULT;
 
   Status GetInt8(const Slice& col_name, int8_t* val) const WARN_UNUSED_RESULT;
@@ -126,10 +165,26 @@ class KUDU_EXPORT KuduScanBatch::RowPtr {
 
   Status GetFloat(const Slice& col_name, float* val) const WARN_UNUSED_RESULT;
   Status GetDouble(const Slice& col_name, double* val) const WARN_UNUSED_RESULT;
-
-  // Same as above getters, but with numeric column indexes.
-  // These are faster since they avoid a hashmap lookup, so should
-  // be preferred in performance-sensitive code.
+  ///@}
+
+  /// @name Getters for integral type columns by column index.
+  ///
+  /// These methods are faster than their name-based counterparts
+  /// since using indices avoids a hashmap lookup, so index-based getters
+  /// should be preferred in performance-sensitive code.
+  ///
+  /// @param [in] col_index
+  ///   The index of the column.
+  /// @param [out] val
+  ///   Pointer to the placeholder to put the resulting value.
+  ///
+  /// @return Operation result status. Return a bad Status if at least one
+  ///   of the following is @c true:
+  ///     @li The type does not match.
+  ///     @li The value is unset.
+  ///     @li The value is @c NULL.
+  ///
+  ///@{
   Status GetBool(int col_idx, bool* val) const WARN_UNUSED_RESULT;
 
   Status GetInt8(int col_idx, int8_t* val) const WARN_UNUSED_RESULT;
@@ -140,17 +195,63 @@ class KUDU_EXPORT KuduScanBatch::RowPtr {
 
   Status GetFloat(int col_idx, float* val) const WARN_UNUSED_RESULT;
   Status GetDouble(int col_idx, double* val) const WARN_UNUSED_RESULT;
-
-  // Gets the string/binary value but does not copy the value. Callers should
-  // copy the resulting Slice if necessary.
+  ///@}
+
+  /// @name Getters for string/binary column by column name.
+  ///
+  /// Get the string/binary value for a column by its name.
+  ///
+  /// @param [in] col_name
+  ///   Name of the column.
+  /// @param [out] val
+  ///   Pointer to the placeholder to put the resulting value.
+  ///   Note that the method does not copy the value. Callers should copy
+  ///   the resulting Slice if necessary.
+  /// @return Operation result status. Return a bad Status if at least one
+  ///   of the following is @c true:
+  ///     @li The type does not match.
+  ///     @li The value is unset.
+  ///     @li The value is @c NULL.
+  ///
+  ///@{
   Status GetString(const Slice& col_name, Slice* val) const WARN_UNUSED_RESULT;
-  Status GetString(int col_idx, Slice* val) const WARN_UNUSED_RESULT;
   Status GetBinary(const Slice& col_name, Slice* val) const WARN_UNUSED_RESULT;
+  ///@}
+
+  /// @name Getters for string/binary column by column index.
+  ///
+  /// Get the string/binary value for a column by its index.
+  ///
+  /// These methods are faster than their name-based counterparts
+  /// since using indices avoids a hashmap lookup, so index-based getters
+  /// should be preferred in performance-sensitive code.
+  ///
+  /// @param [in] col_index
+  ///   The index of the column.
+  /// @param [out] val
+  ///   Pointer to the placeholder to put the resulting value.
+  ///   Note that the method does not copy the value. Callers should copy
+  ///   the resulting Slice if necessary.
+  /// @return Operation result status. Return a bad Status if at least one
+  ///   of the following is @c true:
+  ///     @li The type does not match.
+  ///     @li The value is unset.
+  ///     @li The value is @c NULL.
+  ///
+  ///@{
+  Status GetString(int col_idx, Slice* val) const WARN_UNUSED_RESULT;
   Status GetBinary(int col_idx, Slice* val) const WARN_UNUSED_RESULT;
-
-  // Raw cell access. Should be avoided unless absolutely necessary.
+  ///@}
+
+  /// Get the column's row data.
+  ///
+  /// @note Should be avoided unless absolutely necessary.
+  /// @param [in] col_idx
+  ///   The index of the column.
+  /// @return Raw cell data for the specified index.
   const void* cell(int col_idx) const;
 
+  /// @return String representation for this row.
   std::string ToString() const;
 
  private:
@@ -175,38 +276,50 @@ class KUDU_EXPORT KuduScanBatch::RowPtr {
   const uint8_t* row_data_;
 };
 
-// C++ forward iterator over the rows in a KuduScanBatch.
-//
-// This iterator yields KuduScanBatch::RowPtr objects which point inside the row batch
-// itself. Thus, the iterator and any objects obtained from it are invalidated if the
-// KuduScanBatch is destroyed or used for a new NextBatch() call.
 class KUDU_EXPORT KuduScanBatch::const_iterator
     : public std::iterator<std::forward_iterator_tag, KuduScanBatch::RowPtr> {
  public:
   ~const_iterator() {}
 
+  /// @return The row in the batch the iterator is pointing at.
   KuduScanBatch::RowPtr operator*() const {
     return batch_->Row(idx_);
   }
 
-  // Prefix increment operator: advances the iterator to the next position.
-  // Returns the reference to the incremented/advanced iterator.
+  /// Prefix increment operator: advances the iterator to the next position.
+  ///
+  /// @return The reference to the iterator, pointing to the next position.
   const_iterator& operator++() {
     ++idx_;
     return *this;
   }
 
-  // Postfix increment operator: advances the iterator to the next position.
-  // Returns a copy of the iterator pointing to the pre-incremented position.
+  /// Postfix increment operator: advances the iterator to the next position.
+  ///
+  /// @return A copy of the iterator pointing to the pre-increment position.
   const_iterator operator++(int) {
     const_iterator tmp(batch_, idx_);
     ++idx_;
     return tmp;
   }
 
+  /// An operator to check whether two iterators are 'equal'.
+  ///
+  /// @param [in] other
+  ///   The iterator to compare with.
+  /// @return @c true iff the other iterator points to the same row
+  ///   of the same batch.
   bool operator==(const const_iterator& other) const {
     return (idx_ == other.idx_) && (batch_ == other.batch_);
   }
+
+  /// An operator to check whether two iterators are 'not equal'.
+  ///
+  /// @param [in] other
+  ///   The iterator to compare with.
+  /// @return @c true iff the other iterator points to a different row
+  ///   in the same batch, or to a row belonging to a different batch
+  ///   altogether.
   bool operator!=(const const_iterator& other) const {
     return !(*this == other);
   }

http://git-wip-us.apache.org/repos/asf/kudu/blob/88fe33c9/src/kudu/client/scan_predicate.h
----------------------------------------------------------------------
diff --git a/src/kudu/client/scan_predicate.h b/src/kudu/client/scan_predicate.h
index c1586fe..99736c5 100644
--- a/src/kudu/client/scan_predicate.h
+++ b/src/kudu/client/scan_predicate.h
@@ -30,8 +30,12 @@
 namespace kudu {
 namespace client {
 
+/// @brief A representation of comparison predicate for Kudu queries.
+///
+/// Call KuduTable::NewComparisonPredicate() to create a predicate object.
 class KUDU_EXPORT KuduPredicate {
  public:
+  /// @brief Supported comparison operators.
   enum ComparisonOp {
     LESS_EQUAL,
     GREATER_EQUAL,
@@ -42,11 +46,13 @@ class KUDU_EXPORT KuduPredicate {
 
   ~KuduPredicate();
 
-  // Returns a new, identical, KuduPredicate.
+  /// @return A new, identical, KuduPredicate object.
   KuduPredicate* Clone() const;
 
-  // The PIMPL class has to be public since it's actually just an interface,
-  // and gcc gives an error trying to derive from a private nested class.
+  /// @brief Forward declaration for the embedded PIMPL class.
+  ///
+  /// The PIMPL class has to be public since it's actually just an interface,
+  /// and gcc gives an error trying to derive from a private nested class.
   class KUDU_NO_EXPORT Data;
  private:
   friend class ComparisonPredicateData;

http://git-wip-us.apache.org/repos/asf/kudu/blob/88fe33c9/src/kudu/client/schema.h
----------------------------------------------------------------------
diff --git a/src/kudu/client/schema.h b/src/kudu/client/schema.h
index 65fb5c3..099185a 100644
--- a/src/kudu/client/schema.h
+++ b/src/kudu/client/schema.h
@@ -1,4 +1,3 @@
-
 //
 // Licensed to the Apache Software Foundation (ASF) under one
 // or more contributor license agreements.  See the NOTICE file
@@ -50,8 +49,10 @@ class KuduSchema;
 class KuduSchemaBuilder;
 class KuduWriteOperation;
 
+/// @brief Representation of column storage attributes.
 class KUDU_EXPORT KuduColumnStorageAttributes {
  public:
+  /// @brief Column encoding types.
   enum EncodingType {
     AUTO_ENCODING = 0,
     PLAIN_ENCODING = 1,
@@ -62,6 +63,7 @@ class KUDU_EXPORT KuduColumnStorageAttributes {
     BIT_SHUFFLE = 6
   };
 
+  /// @brief Column compression types.
   enum CompressionType {
     DEFAULT_COMPRESSION = 0,
     NO_COMPRESSION = 1,
@@ -71,8 +73,17 @@ class KUDU_EXPORT KuduColumnStorageAttributes {
   };
 
 
-  // NOTE: this constructor is deprecated for external use, and will
-  // be made private in a future release.
+  /// @deprecated This constructor is deprecated for external use, and will
+  ///   be made private in a future release.
+  ///
+  /// @todo Make this constructor private.
+  ///
+  /// @param [in] encoding
+  ///   Encoding type for the column storage.
+  /// @param [in] compression
+  ///   Compression type for the column storage.
+  /// @param [in] block_size
+  ///   Block size (in bytes, uncompressed data) for the column storage.
   KuduColumnStorageAttributes(EncodingType encoding = AUTO_ENCODING,
                               CompressionType compression = DEFAULT_COMPRESSION,
                               int32_t block_size = 0)
@@ -81,14 +92,17 @@ class KUDU_EXPORT KuduColumnStorageAttributes {
       block_size_(block_size) {
   }
 
+  /// @return Encoding type for the column storage.
   const EncodingType encoding() const {
     return encoding_;
   }
 
+  /// @return Comporession type for the column storage.
   const CompressionType compression() const {
     return compression_;
   }
 
+  /// @return String representation of the storage attributes.
   std::string ToString() const;
 
  private:
@@ -97,8 +111,10 @@ class KUDU_EXPORT KuduColumnStorageAttributes {
   int32_t block_size_;
 };
 
+/// @brief Representation of the column schema.
 class KUDU_EXPORT KuduColumnSchema {
  public:
+  /// @brief Supported data types for columns.
   enum DataType {
     INT8 = 0,
     INT16 = 1,
@@ -112,31 +128,74 @@ class KUDU_EXPORT KuduColumnSchema {
     TIMESTAMP = 9
   };
 
+  /// @param [in] type
+  ///   Column data type.
+  /// @return String representation of the column data type.
   static std::string DataTypeToString(DataType type);
 
-  // DEPRECATED: use KuduSchemaBuilder instead.
-  // TODO(KUDU-809): make this hard-to-use constructor private. Clients should use
-  // the Builder API. Currently only the Python API uses this old API.
+  /// @deprecated Use KuduSchemaBuilder instead.
+  ///
+  /// @todo KUDU-809: make this hard-to-use constructor private.
+  ///   Clients should use the Builder API. Currently only the Python API
+  ///   uses this old API.
+  ///
+  /// @param [in] name
+  ///   The name of the column.
+  /// @param [in] type
+  ///   The type of the column.
+  /// @param [in] is_nullable
+  ///   Whether the column is nullable.
+  /// @param [in] default_value
+  ///   Default value for the column.
+  /// @param [in] attributes
+  ///   Column storage attributes.
   KuduColumnSchema(const std::string &name,
                    DataType type,
                    bool is_nullable = false,
                    const void* default_value = NULL,
                    KuduColumnStorageAttributes attributes = KuduColumnStorageAttributes());
+
+  /// Construct KuduColumnSchema object as a copy of another object.
+  ///
+  /// @param [in] other
+  ///   The reference object to copy from.
   KuduColumnSchema(const KuduColumnSchema& other);
   ~KuduColumnSchema();
 
+  /// The assignment operator.
+  ///
+  /// @param [in] other
+  ///   The reference object to assign from.
+  /// @return The updated object.
   KuduColumnSchema& operator=(const KuduColumnSchema& other);
 
+  /// Make this object an identical copy of the other one.
+  ///
+  /// @param [in] other
+  ///   The reference object to copy from.
   void CopyFrom(const KuduColumnSchema& other);
 
+  /// Check whether the object is identical to the other one.
+  ///
+  /// @param [in] other
+  ///   The reference object to compare with.
+  /// @return @c true iff the object is identical to the specified one.
   bool Equals(const KuduColumnSchema& other) const;
 
-  // Getters to expose column schema information.
+  /// @name Getters to expose column schema information.
+  ///
+  /// @todo Expose default column value and attributes?
+  ///
+  ///@{
+  /// @return Name of the column schema.
   const std::string& name() const;
+
+  /// @return Type of the column schema.
   DataType type() const;
-  bool is_nullable() const;
 
-  // TODO: Expose default column value and attributes?
+  /// @return @c true iff the column schema has the nullable attribute set.
+  bool is_nullable() const;
+  ///@}
 
  private:
   friend class KuduColumnSpec;
@@ -152,82 +211,122 @@ class KUDU_EXPORT KuduColumnSchema {
   ColumnSchema* col_;
 };
 
-// Builder API for specifying or altering a column within a table schema.
-// This cannot be constructed directly, but rather is returned from
-// KuduSchemaBuilder::AddColumn() to specify a column within a Schema.
-//
-// TODO(KUDU-861): this API will also be used for an improved AlterTable API.
+/// @brief Builder API for specifying or altering a column
+///   within a table schema.
+///
+/// An object of this type cannot be constructed directly, but rather
+/// is returned from KuduSchemaBuilder::AddColumn() to specify a column
+/// within a Schema.
+///
+/// @todo KUDU-861: this API will also be used for an improved AlterTable API.
 class KUDU_EXPORT KuduColumnSpec {
  public:
-  // Set the default value for this column.
-  //
-  // When adding a new column to a table, this default value will be used to
-  // fill the new column in all existing rows.
-  //
-  // When a user inserts data, if the user does not specify any value for
-  // this column, the default will also be used.
-  //
-  // The KuduColumnSpec takes ownership over 'value'.
+  /// Set the default value for the column.
+  ///
+  /// When adding a new column to a table, this default value will be used to
+  /// fill the new column in all existing rows. The default value
+  /// will also be used when inserting a new row with no value for the column.
+  ///
+  /// @param [in] value
+  ///   The value to use as the default. The KuduColumnSpec takes ownership
+  ///   over the passed parameter.
+  ///
+  /// @return Pointer to the modified object.
   KuduColumnSpec* Default(KuduValue* value);
 
-  // Set the preferred compression for this column.
+  /// Set the preferred compression type for the column.
+  ///
+  /// @param [in] compression
+  ///   The compression type to use.
+  /// @return Pointer to the modified object.
   KuduColumnSpec* Compression(KuduColumnStorageAttributes::CompressionType compression);
 
-  // Set the preferred encoding for this column.
-  // Note that not all encodings are supported for all column types.
+  /// Set the preferred encoding for the column.
+  ///
+  /// @note Not all encodings are supported for all column types.
+  ///
+  /// @param [in] encoding
+  ///   The encoding to use.
+  /// @return Pointer to the modified object.
   KuduColumnSpec* Encoding(KuduColumnStorageAttributes::EncodingType encoding);
 
-  // Set the target block size for this column.
-  //
-  // This is the number of bytes of user data packed per block on disk, and
-  // represents the unit of IO when reading this column. Larger values
-  // may improve scan performance, particularly on spinning media. Smaller
-  // values may improve random access performance, particularly for workloads
-  // that have high cache hit rates or operate on fast storage such as SSD.
-  //
-  // Note that the block size specified here corresponds to uncompressed data.
-  // The actual size of the unit read from disk may be smaller if
-  // compression is enabled.
-  //
-  // It's recommended that this not be set any lower than 4096 (4KB) or higher
-  // than 1048576 (1MB).
-  // TODO(KUDU-1107): move above info to docs
+  /// Set the target block size for the column.
+  ///
+  /// This is the number of bytes of user data packed per block on disk, and
+  /// represents the unit of IO when reading the column. Larger values
+  /// may improve scan performance, particularly on spinning media. Smaller
+  /// values may improve random access performance, particularly for workloads
+  /// that have high cache hit rates or operate on fast storage such as SSD.
+  ///
+  /// @note The block size specified here corresponds to uncompressed data.
+  ///   The actual size of the unit read from disk may be smaller if
+  ///   compression is enabled.
+  ///
+  /// @note It's recommended that this not be set any lower than 4096 (4KB)
+  ///   or higher than 1048576 (1MB).
+  /// @todo KUDU-1107: move above info to docs
+  ///
+  /// @param [in] block_size
+  ///   Block size (in bytes) to use.
+  /// @return Pointer to the modified object.
   KuduColumnSpec* BlockSize(int32_t block_size);
 
-  // Operations only relevant for Create Table
-  // ------------------------------------------------------------
-
-  // Set this column to be the primary key of the table.
-  //
-  // This may only be used to set non-composite primary keys. If a composite
-  // key is desired, use KuduSchemaBuilder::SetPrimaryKey(). This may not be
-  // used in conjunction with KuduSchemaBuilder::SetPrimaryKey().
-  //
-  // Only relevant for a CreateTable operation. Primary keys may not be changed
-  // after a table is created.
+  /// @name Operations only relevant for Create Table
+  ///
+  ///@{
+  /// Set the column to be the primary key of the table.
+  ///
+  /// This may only be used to set non-composite primary keys. If a composite
+  /// key is desired, use KuduSchemaBuilder::SetPrimaryKey(). This may not be
+  /// used in conjunction with KuduSchemaBuilder::SetPrimaryKey().
+  ///
+  /// @note Primary keys may not be changed after a table is created.
+  ///
+  /// @return Pointer to the modified object.
   KuduColumnSpec* PrimaryKey();
 
-  // Set this column to be not nullable.
-  // Column nullability may not be changed once a table is created.
+  /// Set the column to be not nullable.
+  ///
+  /// @note Column nullability may not be changed once a table is created.
+  ///
+  /// @return Pointer to the modified object.
   KuduColumnSpec* NotNull();
 
-  // Set this column to be nullable (the default).
-  // Column nullability may not be changed once a table is created.
+  /// Set the column to be nullable (the default).
+  ///
+  /// @note Column nullability may not be changed once a table is created.
+  ///
+  /// @return Pointer to the modified object.
   KuduColumnSpec* Nullable();
 
-  // Set the type of this column.
-  // Column types may not be changed once a table is created.
+  /// Set the data type of the column.
+  ///
+  /// @note Column data types may not be changed once a table is created.
+  ///
+  /// @param [in] type
+  ///   The data type to set.
+  /// @return Pointer to the modified object.
   KuduColumnSpec* Type(KuduColumnSchema::DataType type);
-
-  // Operations only relevant for Alter Table
-  // ------------------------------------------------------------
-
-  // Remove the default value for this column. Without a default, clients must
-  // always specify a value for this column when inserting data.
+  ///@}
+
+  /// @name Operations only relevant for Alter Table
+  ///
+  ///@{
+  /// Remove the default value for the column.
+  ///
+  /// Without a default, clients must always specify a value for the column
+  /// when inserting data.
+  ///
+  /// @return Pointer to the modified object.
   KuduColumnSpec* RemoveDefault();
 
-  // Rename this column.
+  /// Rename the column.
+  ///
+  /// @param [in] new_name
+  ///   The new name for the column.
+  /// @return Pointer to the modified object.
   KuduColumnSpec* RenameTo(const std::string& new_name);
+  ///@}
 
  private:
   class KUDU_NO_EXPORT Data;
@@ -246,41 +345,58 @@ class KUDU_EXPORT KuduColumnSpec {
   Data* data_;
 };
 
-// Builder API for constructing a KuduSchema object.
-// The API here is a "fluent" style of programming, such that the resulting code
-// looks somewhat like a SQL "CREATE TABLE" statement. For example:
-//
-// SQL:
-//   CREATE TABLE t (
-//     my_key int not null primary key,
-//     a float default 1.5
-//   );
-//
-// is represented as:
-//
-//   KuduSchemaBuilder t;
-//   t.AddColumn("my_key")->Type(KuduColumnSchema::INT32)->NotNull()->PrimaryKey();
-//   t.AddColumn("a")->Type(KuduColumnSchema::FLOAT)->Default(KuduValue::FromFloat(1.5));
-//   KuduSchema schema;
-//   t.Build(&schema);
-//
+/// @brief Builder API for constructing a KuduSchema object.
+///
+/// The API here is a "fluent" style of programming, such that the resulting
+/// code looks somewhat like a SQL "CREATE TABLE" statement. For example:
+///
+/// SQL:
+/// @code
+///   CREATE TABLE t (
+///     my_key int not null primary key,
+///     a float default 1.5
+///   );
+/// @endcode
+///
+/// is represented as:
+/// @code
+///   KuduSchemaBuilder t;
+///   t.AddColumn("my_key")->Type(KuduColumnSchema::INT32)->NotNull()->PrimaryKey();
+///   t.AddColumn("a")->Type(KuduColumnSchema::FLOAT)->Default(KuduValue::FromFloat(1.5));
+///   KuduSchema schema;
+///   t.Build(&schema);
+/// @endcode
 class KUDU_EXPORT KuduSchemaBuilder {
  public:
   KuduSchemaBuilder();
   ~KuduSchemaBuilder();
 
-  // Return a KuduColumnSpec for a new column within the Schema.
-  // The returned object is owned by the KuduSchemaBuilder.
+  /// Add a column with the specified name to the schema.
+  ///
+  /// @param [in] name
+  ///   Name of the column to add.
+  /// @return A KuduColumnSpec object for a new column within the Schema.
+  ///   The returned object is owned by the KuduSchemaBuilder.
   KuduColumnSpec* AddColumn(const std::string& name);
 
-  // Set the primary key of the new Schema based on the given column names.
-  // This may be used to specify a compound primary key.
+  /// Set the primary key of the new Schema based on the given column names.
+  ///
+  /// This may be used to specify a compound primary key.
+  ///
+  /// @param [in] key_col_names
+  ///   Names of the columns to include into the compound primary key.
+  /// @return Pointer to the modified object.
   KuduSchemaBuilder* SetPrimaryKey(const std::vector<std::string>& key_col_names);
 
-  // Resets 'schema' to the result of this builder.
-  //
-  // If the Schema is invalid for any reason (eg missing types, duplicate column names, etc)
-  // a bad Status will be returned.
+  /// Build the schema based on current configuration of the builder object.
+  ///
+  /// @param [out] schema
+  ///   The placeholder for the result schema. Upon successful completion,
+  ///   the parameter is reset to the result of this builder: literally,
+  ///   calling KuduSchema::Reset() on the parameter.
+  /// @return Operation result status. If the resulting would-be-schema
+  ///   is invalid for any reason (e.g. missing types, duplicate column names,
+  ///   etc.) a bad Status is returned.
   Status Build(KuduSchema* schema);
 
  private:
@@ -289,36 +405,73 @@ class KUDU_EXPORT KuduSchemaBuilder {
   Data* data_;
 };
 
+/// @brief A representation of a table's schema.
 class KUDU_EXPORT KuduSchema {
  public:
   KuduSchema();
 
+  /// Create a KuduSchema object as a copy of the other one.
+  ///
+  /// @param [in] other
+  ///   The other KuduSchema object to use as a reference.
   KuduSchema(const KuduSchema& other);
   ~KuduSchema();
 
+  /// @name Assign/copy the schema
+  ///
+  /// @param [in] other
+  ///   The source KuduSchema object to use as a reference.
+  ///
+  ///@{
   KuduSchema& operator=(const KuduSchema& other);
   void CopyFrom(const KuduSchema& other);
-
-  // DEPRECATED: will be removed soon.
+  ///@}
+
+  /// @deprecated This method will be removed soon.
+  ///
+  /// @todo Remove KuduSchema::Reset().
+  ///
+  /// @param [in] columns
+  ///   Per-column schema information.
+  /// @param [in] key_columns
+  ///   Number of key columns in the schema.
+  /// @return Operation result status.
   Status Reset(const std::vector<KuduColumnSchema>& columns, int key_columns)
     WARN_UNUSED_RESULT;
 
+  /// Check whether the schema is identical to the other one.
+  ///
+  /// @param [in] other
+  ///   The other KuduSchema object to compare with.
+  /// @return @c true iff this KuduSchema object is identical
+  ///   to the specified one.
   bool Equals(const KuduSchema& other) const;
+
+  /// @param [in] idx
+  ///   Column index.
+  /// @return Schema for the specified column.
   KuduColumnSchema Column(size_t idx) const;
+
+  /// @return The number of columns in the schema.
   size_t num_columns() const;
 
-  // Get the indexes of the primary key columns within this Schema.
-  // In current versions of Kudu, these will always be contiguous column
-  // indexes starting with 0. However, in future versions this assumption
-  // may not hold, so callers should not assume it is the case.
+  /// Get the indexes of the primary key columns within this Schema.
+  ///
+  /// @attention In current versions of Kudu, these will always be contiguous
+  ///   column indexes starting with 0. However, in future versions this
+  ///   assumption may not hold, so callers should not assume it is the case.
+  ///
+  /// @param [out] indexes
+  ///   The placeholder for the result.
   void GetPrimaryKeyColumnIndexes(std::vector<int>* indexes) const;
 
-  // Create a new row corresponding to this schema.
-  //
-  // The new row refers to this KuduSchema object, so must be destroyed before
-  // the KuduSchema object.
-  //
-  // The caller takes ownership of the created row.
+  /// Create a new row corresponding to this schema.
+  ///
+  /// @note The new row refers to this KuduSchema object, so it must be
+  ///   destroyed before the KuduSchema object to avoid dangling pointers.
+  ///
+  /// @return A pointer to the newly created row. The caller takes ownership
+  ///   of the created row.
   KuduPartialRow* NewRow() const;
 
  private:

http://git-wip-us.apache.org/repos/asf/kudu/blob/88fe33c9/src/kudu/client/shared_ptr.h
----------------------------------------------------------------------
diff --git a/src/kudu/client/shared_ptr.h b/src/kudu/client/shared_ptr.h
index 2cc8c16..731b8cb 100644
--- a/src/kudu/client/shared_ptr.h
+++ b/src/kudu/client/shared_ptr.h
@@ -18,20 +18,20 @@
 #ifndef KUDU_CLIENT_SHARED_PTR_H
 #define KUDU_CLIENT_SHARED_PTR_H
 
-// Kudu uses c++11 features internally, but provides a client interface which
-// does not require c++11. We use std::tr1::shared_ptr in our public interface
-// to hold shared instances of KuduClient, KuduSession, and KuduTable.
-//
-// Unfortunately, on OS X, libc++ is the default c++ standard library
-// implementation and is required when compiling with c++11, but it does not
-// include the tr1 APIs. As a workaround, we use std::shared_ptr on OS X, since
-// OS X is for development only, and it is acceptable to require clients to
-// compile with c++11.
-//
-// In order to allow applications to compile against Kudu on both Linux and OS
-// X, we provide this typedef which resolves to std::tr1::shared_ptr on Linux
-// and std::shared_ptr on OS X. Clients are encouraged to use these typedefs in
-// order to ensure that applications will compile on both Linux and OS X.
+/// Kudu uses c++11 features internally, but provides a client interface which
+/// does not require c++11. We use std::tr1::shared_ptr in our public interface
+/// to hold shared instances of KuduClient, KuduSession, and KuduTable.
+///
+/// Unfortunately, on OS X, libc++ is the default c++ standard library
+/// implementation and is required when compiling with c++11, but it does not
+/// include the tr1 APIs. As a workaround, we use std::shared_ptr on OS X, since
+/// OS X is for development only, and it is acceptable to require clients to
+/// compile with c++11.
+///
+/// In order to allow applications to compile against Kudu on both Linux and OS
+/// X, we provide this typedef which resolves to std::tr1::shared_ptr on Linux
+/// and std::shared_ptr on OS X. Clients are encouraged to use these typedefs in
+/// order to ensure that applications will compile on both Linux and OS X.
 
 #if defined(__APPLE__)
 #include <memory>

http://git-wip-us.apache.org/repos/asf/kudu/blob/88fe33c9/src/kudu/client/stubs.h
----------------------------------------------------------------------
diff --git a/src/kudu/client/stubs.h b/src/kudu/client/stubs.h
index a52bf77..f2158fc 100644
--- a/src/kudu/client/stubs.h
+++ b/src/kudu/client/stubs.h
@@ -170,16 +170,30 @@ namespace kudu {
 
 namespace internal_logging {
 
+/// @brief A helper for the nil log sink.
+///
+/// Using this helper is analogous to sending log messages to /dev/null:
+/// nothing gets logged.
 class NullLog {
  public:
+  /// The no-op output operator.
+  ///
+  /// @param [in] t
+  ///   The object to send into the nil sink.
+  /// @return Reference to the updated object.
   template<class T>
   NullLog& operator<<(const T& t) {
     return *this;
   }
 };
 
+/// @brief A helper for stderr log sink.
 class CerrLog {
  public:
+  /// Create a CerrLog sink helper object.
+  ///
+  /// @param [in] severity
+  ///   The severity for log messages output to the sink (stderr).
   CerrLog(int severity) // NOLINT(runtime/explicit)
     : severity_(severity),
       has_logged_(false) {
@@ -194,6 +208,11 @@ class CerrLog {
     }
   }
 
+  /// The output operator.
+  ///
+  /// @param [in] t
+  ///   The object to print into stderr.
+  /// @return Reference to the updated object.
   template<class T>
   CerrLog& operator<<(const T& t) {
     has_logged_ = true;

http://git-wip-us.apache.org/repos/asf/kudu/blob/88fe33c9/src/kudu/client/value.h
----------------------------------------------------------------------
diff --git a/src/kudu/client/value.h b/src/kudu/client/value.h
index 5ec4031..03a38f5 100644
--- a/src/kudu/client/value.h
+++ b/src/kudu/client/value.h
@@ -29,25 +29,32 @@
 namespace kudu {
 namespace client {
 
-// A constant cell value with a specific type.
+/// @brief A constant cell value with a specific type.
 class KUDU_EXPORT KuduValue {
  public:
-  // Return a new identical KuduValue object.
+  /// @return A new identical KuduValue object.
   KuduValue* Clone() const;
 
-  // Construct a KuduValue from the given integer.
-  static KuduValue* FromInt(int64_t v);
-
-  // Construct a KuduValue from the given float.
+  /// @name Builders from integral types.
+  ///
+  /// Construct a KuduValue object from the given value of integral type.
+  ///
+  /// @param [in] val
+  ///   The value to build the KuduValue from.
+  /// @return A new KuduValue object.
+  ///
+  ///@{
+  static KuduValue* FromInt(int64_t val);
   static KuduValue* FromFloat(float f);
-
-  // Construct a KuduValue from the given double.
   static KuduValue* FromDouble(double d);
-
-  // Construct a KuduValue from the given bool.
   static KuduValue* FromBool(bool b);
+  ///@}
 
-  // Construct a KuduValue by copying the value of the given Slice.
+  /// Construct a KuduValue by copying the value of the given Slice.
+  ///
+  /// @param [in] s
+  ///   The slice to copy value from.
+  /// @return A new KuduValue object.
   static KuduValue* CopyString(Slice s);
 
   ~KuduValue();

http://git-wip-us.apache.org/repos/asf/kudu/blob/88fe33c9/src/kudu/client/write_op.h
----------------------------------------------------------------------
diff --git a/src/kudu/client/write_op.h b/src/kudu/client/write_op.h
index 51e16a0..b534f1d 100644
--- a/src/kudu/client/write_op.h
+++ b/src/kudu/client/write_op.h
@@ -36,23 +36,25 @@ class WriteRpc;
 
 class KuduTable;
 
-// A single-row write operation to be sent to a Kudu table.
-//
-// This is the abstract base class from which the particular row operations
-// (KuduInsert, KuduUpdate, etc) are derived. These subclasses are instantiated
-// by KuduTable::NewInsert(), etc.
-//
-// The row key, as well as the columns to be inserted or updated are set using
-// the embedded KuduPartialRow object accessible via mutable_row().
-//
-// Typical usage example:
-//
-//   KuduInsert* t = table->NewInsert();
-//   KUDU_CHECK_OK(t->mutable_row()->SetInt32("key", 1234));
-//   KUDU_CHECK_OK(t->mutable_row()->SetStringCopy("foo", "bar"));
-//   session->Apply(t);
+/// @brief A single-row write operation to be sent to a Kudu table.
+///
+/// This is the abstract base class from which the particular row operations
+/// (KuduInsert, KuduUpdate, etc) are derived. These subclasses are instantiated
+/// by KuduTable::NewInsert(), etc.
+///
+/// The row key, as well as the columns to be inserted or updated are set using
+/// the embedded KuduPartialRow object accessible via mutable_row().
+///
+/// Typical usage example:
+/// @code
+///   KuduInsert* t = table->NewInsert();
+///   KUDU_CHECK_OK(t->mutable_row()->SetInt32("key", 1234));
+///   KUDU_CHECK_OK(t->mutable_row()->SetStringCopy("foo", "bar"));
+///   session->Apply(t);
+/// @endcode
 class KUDU_EXPORT KuduWriteOperation {
  public:
+  /// @brief Write operation types.
   enum Type {
     INSERT = 1,
     UPDATE = 2,
@@ -61,20 +63,40 @@ class KUDU_EXPORT KuduWriteOperation {
   };
   virtual ~KuduWriteOperation();
 
-  // See KuduPartialRow API for field setters, etc.
+  /// @note To work with a row, use the KuduPartialRow API for field getters,
+  ///   etc.
+  /// @return Immutable reference to the corresponding row-like object.
   const KuduPartialRow& row() const { return row_; }
+
+  /// @note To work with a row, use the KuduPartialRow API for field setters,
+  ///   etc.
+  /// @return Pointer to the corresponding row-like object.
   KuduPartialRow* mutable_row() { return &row_; }
 
+  /// @return String representation of the operation.
   virtual std::string ToString() const = 0;
  protected:
+  /// @cond PROTECTED_MEMBERS_DOCUMENTED
+
+  /// Create a write operation on the specified table.
+  ///
+  /// @param [in] table
+  ///   Smart pointer to the target table.
   explicit KuduWriteOperation(const sp::shared_ptr<KuduTable>& table);
+
+  /// @return Type of the operation.
   virtual Type type() const = 0;
 
-  // KuduWriteOperation holds shared ownership of its KuduTable to allow the client's
-  // scope to end while the KuduWriteOperation is still alive.
+  /// KuduWriteOperation holds shared ownership of its KuduTable
+  /// to allow the client's scope to end while the KuduWriteOperation
+  /// is still alive.
   sp::shared_ptr<KuduTable> const table_;
+
+  /// The partial row to access schema-related properties.
   KuduPartialRow row_;
 
+  /// @endcond
+
  private:
   friend class internal::Batcher;
   friend class internal::WriteRpc;
@@ -94,77 +116,106 @@ class KUDU_EXPORT KuduWriteOperation {
 };
 
 
-// A single row insert to be sent to the cluster.
-// An insert requires all key columns to be set, as well as all
-// columns which do not have default values.
+/// @brief A single row insert to be sent to the cluster.
+///
+/// @pre An insert requires all key columns to be set, as well as all
+///   columns which do not have default values.
 class KUDU_EXPORT KuduInsert : public KuduWriteOperation {
  public:
   virtual ~KuduInsert();
 
+  /// @copydoc KuduWriteOperation::ToString()
   virtual std::string ToString() const OVERRIDE { return "INSERT " + row_.ToString(); }
 
  protected:
+  /// @cond PROTECTED_MEMBERS_DOCUMENTED
+
+  /// @copydoc KuduWriteOperation::type()
   virtual Type type() const OVERRIDE {
     return INSERT;
   }
 
+  /// @endcond
+
  private:
   friend class KuduTable;
   explicit KuduInsert(const sp::shared_ptr<KuduTable>& table);
 };
 
-// A single row upsert to be sent to the cluster.
-// See KuduInsert for more details.
+/// @brief A single row upsert to be sent to the cluster.
+///
+/// See KuduInsert for more details.
 class KUDU_EXPORT KuduUpsert : public KuduWriteOperation {
  public:
   virtual ~KuduUpsert();
 
+  /// @copydoc KuduWriteOperation::ToString()
   virtual std::string ToString() const OVERRIDE { return "UPSERT " + row_.ToString(); }
 
  protected:
+  /// @cond PROTECTED_MEMBERS_DOCUMENTED
+
+  /// @copydoc KuduWriteOperation::type()
   virtual Type type() const OVERRIDE {
     return UPSERT;
   }
 
+  /// @endcond
+
  private:
   friend class KuduTable;
   explicit KuduUpsert(const sp::shared_ptr<KuduTable>& table);
 };
 
 
-// A single row update to be sent to the cluster.
-// An update requires the key columns and at least one other column
-// in the schema to be set in the embedded PartialRow object.
+/// @brief A single row update to be sent to the cluster.
+///
+/// @pre An update requires the key columns and at least one other column
+///   in the schema to be set in the embedded KuduPartialRow object.
 class KUDU_EXPORT KuduUpdate : public KuduWriteOperation {
  public:
   virtual ~KuduUpdate();
 
+  /// @copydoc KuduWriteOperation::ToString()
   virtual std::string ToString() const OVERRIDE { return "UPDATE " + row_.ToString(); }
 
  protected:
+  /// @cond PROTECTED_MEMBERS_DOCUMENTED
+
+  /// @copydoc KuduWriteOperation::type()
   virtual Type type() const OVERRIDE {
     return UPDATE;
   }
 
+  /// @endcond
+
  private:
   friend class KuduTable;
   explicit KuduUpdate(const sp::shared_ptr<KuduTable>& table);
 };
 
 
-// A single row delete to be sent to the cluster.
-// A delete requires the key columns to be set in the embedded PartialRow object.
+/// @brief A single row delete to be sent to the cluster.
+///
+/// @pre A delete requires the key columns to be set in the embedded
+///   KuduPartialRow object.
 class KUDU_EXPORT KuduDelete : public KuduWriteOperation {
  public:
   virtual ~KuduDelete();
 
+  /// @copydoc KuduWriteOperation::ToString()
   virtual std::string ToString() const OVERRIDE { return "DELETE " + row_.ToString(); }
 
  protected:
+  /// @cond PROTECTED_MEMBERS_DOCUMENTED
+
+  /// @copydoc KuduWriteOperation::type()
   virtual Type type() const OVERRIDE {
     return DELETE;
   }
 
+  /// @endcond
+
  private:
   friend class KuduTable;
   explicit KuduDelete(const sp::shared_ptr<KuduTable>& table);

http://git-wip-us.apache.org/repos/asf/kudu/blob/88fe33c9/src/kudu/common/partial_row.h
----------------------------------------------------------------------
diff --git a/src/kudu/common/partial_row.h b/src/kudu/common/partial_row.h
index 66b430f..e9519ab 100644
--- a/src/kudu/common/partial_row.h
+++ b/src/kudu/common/partial_row.h
@@ -45,25 +45,44 @@ template<typename KeyTypeWrapper> struct IntKeysTestSetup;
 class Schema;
 class PartialRowPB;
 
-// A row which may only contain values for a subset of the columns.
-// This type contains a normal contiguous row, plus a bitfield indicating
-// which columns have been set. Additionally, this type may optionally own
-// copies of indirect data for variable length columns.
+/// @brief A row which may only contain values for a subset of the columns.
+///
+/// This object contains a normal contiguous row, plus a bitfield indicating
+/// which columns have been set. Additionally, this type may optionally own
+/// copies of indirect data for variable length columns.
 class KUDU_EXPORT KuduPartialRow {
  public:
-  // The given Schema object must remain valid for the lifetime of this
-  // row.
+  /// @param [in] schema
+  ///   Schema to use for the row. The given Schema object must remain valid
+  ///   for the lifetime of this row.
   explicit KuduPartialRow(const Schema* schema);
+
   virtual ~KuduPartialRow();
 
+  /// Create a copy of KuduPartialRow instance.
+  ///
+  /// @param [in] other
+  ///   KuduPartialRow instance to copy from.
   KuduPartialRow(const KuduPartialRow& other);
 
+  /// Overwrite this KuduPartialRow instance with data from other instance.
+  ///
+  /// @param [in] other
+  ///   KuduPartialRow instance to assign from.
+  /// @return Reference to the updated object.
   KuduPartialRow& operator=(KuduPartialRow other);
 
-  //------------------------------------------------------------
-  // Setters
-  //------------------------------------------------------------
-
+  /// @name Setters for integral type columns by name.
+  ///
+  /// Set value for a column by name.
+  ///
+  /// @param [in] col_name
+  ///   Name of the target column.
+  /// @param [in] val
+  ///   The value to set.
+  /// @return Operation result status.
+  ///
+  ///@{
   Status SetBool(const Slice& col_name, bool val) WARN_UNUSED_RESULT;
 
   Status SetInt8(const Slice& col_name, int8_t val) WARN_UNUSED_RESULT;
@@ -74,10 +93,24 @@ class KUDU_EXPORT KuduPartialRow {
 
   Status SetFloat(const Slice& col_name, float val) WARN_UNUSED_RESULT;
   Status SetDouble(const Slice& col_name, double val) WARN_UNUSED_RESULT;
-
-  // Same as above setters, but with numeric column indexes.
-  // These are faster since they avoid a hashmap lookup, so should
-  // be preferred in performance-sensitive code (eg bulk loaders).
+  ///@}
+
+  /// @name Setters for integral type columns by index.
+  ///
+  /// Set value for a column by index.
+  ///
+  /// These setters are the same as corresponding column-name-based setters,
+  /// but with numeric column indexes. These are faster since they avoid
+  /// hashmap lookups, so should be preferred in performance-sensitive code
+  /// (e.g. bulk loaders).
+  ///
+  /// @param [in] col_idx
+  ///   The index of the target column.
+  /// @param [in] val
+  ///   The value to set.
+  /// @return Operation result status.
+  ///
+  ///@{
   Status SetBool(int col_idx, bool val) WARN_UNUSED_RESULT;
 
   Status SetInt8(int col_idx, int8_t val) WARN_UNUSED_RESULT;
@@ -88,44 +121,156 @@ class KUDU_EXPORT KuduPartialRow {
 
   Status SetFloat(int col_idx, float val) WARN_UNUSED_RESULT;
   Status SetDouble(int col_idx, double val) WARN_UNUSED_RESULT;
-
-  // Sets the string/binary value but does not copy the value. The slice
-  // must remain valid until the call to AppendToPB().
+  ///@}
+
+  /// @name Setters for string/binary columns by name.
+  ///
+  /// Set the string/binary value for a column by name.
+  ///
+  /// @note These methods do not copy the value, so the slice must remain valid
+  ///   until corresponding data is sent to the server.
+  ///
+  /// @param [in] col_name
+  ///   Name of the target column.
+  /// @param [in] val
+  ///   The value to set.
+  /// @return Operation result status.
+  ///
+  ///@{
   Status SetString(const Slice& col_name, const Slice& val) WARN_UNUSED_RESULT;
-  Status SetString(int col_idx, const Slice& val) WARN_UNUSED_RESULT;
   Status SetBinary(const Slice& col_name, const Slice& val) WARN_UNUSED_RESULT;
+  ///@}
+
+  /// @name Setters for string/binary columns by index.
+  ///
+  /// Set the string/binary value for a column by index.
+  ///
+  /// These setters are same as the corresponding column-name-based setters,
+  /// but with numeric column indexes. These are faster since they avoid
+  /// hashmap lookups, so should be preferred in performance-sensitive code
+  /// (e.g. bulk loaders).
+  ///
+  /// @note These methods do not copy the value, so the slice must remain valid
+  ///   until corresponding data is sent to the server.
+  ///
+  /// @param [in] col_idx
+  ///   The index of the target column.
+  /// @param [in] val
+  ///   The value to set.
+  /// @return Operation result status.
+  ///
+  ///@{
   Status SetBinary(int col_idx, const Slice& val) WARN_UNUSED_RESULT;
-
-  // Copies 'val' immediately.
+  Status SetString(int col_idx, const Slice& val) WARN_UNUSED_RESULT;
+  ///@}
+
+  /// @name Setters for string/binary columns by name (copying).
+  ///
+  /// Set the string/binary value for a column by name.
+  ///
+  /// @param [in] col_name
+  ///   Name of the target column.
+  /// @param [in] val
+  ///   The value to set.
+  /// @return Operation result status.
+  ///
+  ///@{
   Status SetStringCopy(const Slice& col_name, const Slice& val) WARN_UNUSED_RESULT;
-  Status SetStringCopy(int col_idx, const Slice& val) WARN_UNUSED_RESULT;
   Status SetBinaryCopy(const Slice& col_name, const Slice& val) WARN_UNUSED_RESULT;
+  ///@}
+
+  /// @name Setters for string/binary columns by index (copying).
+  ///
+  /// Set the string/binary value for a column by index.
+  ///
+  /// @param [in] col_idx
+  ///   The index of the target column.
+  /// @param [in] val
+  ///   The value to set.
+  /// @return Operation result status.
+  ///
+  ///@{
+  Status SetStringCopy(int col_idx, const Slice& val) WARN_UNUSED_RESULT;
   Status SetBinaryCopy(int col_idx, const Slice& val) WARN_UNUSED_RESULT;
-
-  // Set the given column to NULL. This will only succeed on nullable
-  // columns. Use Unset(...) to restore a column to its default.
+  ///@}
+
+  /// Set column value to @c NULL; the column is identified by its name.
+  ///
+  /// This will only succeed on nullable columns. Use Unset() to restore
+  /// column value to its default.
+  ///
+  /// @param [in] col_name
+  ///   Name of the target column.
+  /// @return Operation result status.
   Status SetNull(const Slice& col_name) WARN_UNUSED_RESULT;
+
+  /// Set column value to @c NULL; the column is identified by its index.
+  ///
+  /// This will only succeed on nullable columns. Use Unset() to restore
+  /// column value to its default.
+  ///
+  /// @param [in] col_idx
+  ///   The index of the target column.
+  /// @return Operation result status.
   Status SetNull(int col_idx) WARN_UNUSED_RESULT;
 
-  // Unsets the given column. Note that this is different from setting
-  // it to NULL.
+  /// Unset the given column by name, restoring its default value.
+  ///
+  /// @note This is different from setting it to @c NULL.
+  ///
+  /// @param [in] col_name
+  ///   Name of the target column.
+  /// @return Operation result status.
   Status Unset(const Slice& col_name) WARN_UNUSED_RESULT;
-  Status Unset(int col_idx) WARN_UNUSED_RESULT;
 
-  //------------------------------------------------------------
-  // Getters
-  //------------------------------------------------------------
-  // These getters return a bad Status if the type does not match,
-  // the value is unset, or the value is NULL. Otherwise they return
-  // the current set value in *val.
+  /// Unset the given column by index, restoring its default value.
+  ///
+  /// @note This is different from setting it to @c NULL.
+  ///
+  /// @param [in] col_idx
+  ///   The index of the target column.
+  /// @return Operation result status.
+  Status Unset(int col_idx) WARN_UNUSED_RESULT;
 
-  // Return true if the given column has been specified.
+  /// Check whether the specified column is set for the row.
+  ///
+  /// @param [in] col_name
+  ///   Name of the column.
+  /// @return @c true iff the given column has been specified.
   bool IsColumnSet(const Slice& col_name) const;
+
+  /// Check whether the specified column is set for the row.
+  ///
+  /// @param [in] col_idx
+  ///   The index of the column.
+  /// @return @c true iff the given column has been specified.
   bool IsColumnSet(int col_idx) const;
 
+  /// Check whether the specified column is @c NULL for the row.
+  ///
+  /// @param [in] col_name
+  ///   Name of the target column.
+  /// @return @c true iff the given column's value is @c NULL.
   bool IsNull(const Slice& col_name) const;
+
+  /// Check whether the specified column is @c NULL for the row.
+  ///
+  /// @param [in] col_idx
+  ///   The index of the column.
+  /// @return @c true iff the given column's value is @c NULL.
   bool IsNull(int col_idx) const;
 
+  /// @name Getters for integral type columns by column name.
+  ///
+  /// Get value of the column specified by name.
+  ///
+  /// @return Operation result status. Return a bad Status if at least one
+  ///   of the following is @c true:
+  ///     @li The type does not match.
+  ///     @li The value is unset.
+  ///     @li The value is @c NULL.
+  ///
+  ///@{
   Status GetBool(const Slice& col_name, bool* val) const WARN_UNUSED_RESULT;
 
   Status GetInt8(const Slice& col_name, int8_t* val) const WARN_UNUSED_RESULT;
@@ -137,10 +282,26 @@ class KUDU_EXPORT KuduPartialRow {
 
   Status GetFloat(const Slice& col_name, float* val) const WARN_UNUSED_RESULT;
   Status GetDouble(const Slice& col_name, double* val) const WARN_UNUSED_RESULT;
-
-  // Same as above getters, but with numeric column indexes.
-  // These are faster since they avoid a hashmap lookup, so should
-  // be preferred in performance-sensitive code.
+  ///@}
+
+  /// @name Getters for column of integral type by column index.
+  ///
+  /// Get value of a column of integral type by column index.
+  ///
+  /// These getters are the same as the corresponding column-name-based getters,
+  /// but with numeric column indexes. These are faster since they avoid
+  /// hashmap lookups, so should be preferred in performance-sensitive code
+  /// (e.g. bulk loaders).
+  ///
+  /// @param [in] col_idx
+  ///   The index of the target column.
+  /// @return Operation result status. Return a bad Status if at least one
+  ///   of the following is @c true:
+  ///     @li The type does not match.
+  ///     @li The value is unset.
+  ///     @li The value is @c NULL.
+  ///
+  ///@{
   Status GetBool(int col_idx, bool* val) const WARN_UNUSED_RESULT;
 
   Status GetInt8(int col_idx, int8_t* val) const WARN_UNUSED_RESULT;
@@ -151,42 +312,94 @@ class KUDU_EXPORT KuduPartialRow {
 
   Status GetFloat(int col_idx, float* val) const WARN_UNUSED_RESULT;
   Status GetDouble(int col_idx, double* val) const WARN_UNUSED_RESULT;
-
-  // Gets the string/binary value but does not copy the value. Callers should
-  // copy the resulting Slice if necessary.
+  ///@}
+
+  /// @name Getters for string/binary column by column name.
+  ///
+  /// Get the string/binary value for a column by its name.
+  ///
+  /// @param [in] col_name
+  ///   Name of the column.
+  /// @param [out] val
+  ///   Pointer to the placeholder to put the resulting value.
+  ///   Note that the method does not copy the value. Callers should copy
+  ///   the resulting Slice if necessary.
+  /// @return Operation result status. Return a bad Status if at least one
+  ///   of the following is @c true:
+  ///     @li The type does not match.
+  ///     @li The value is unset.
+  ///     @li The value is @c NULL.
+  ///
+  ///@{
   Status GetString(const Slice& col_name, Slice* val) const WARN_UNUSED_RESULT;
-  Status GetString(int col_idx, Slice* val) const WARN_UNUSED_RESULT;
   Status GetBinary(const Slice& col_name, Slice* val) const WARN_UNUSED_RESULT;
+  ///@}
+
+  /// @name Getters for string/binary column by column index.
+  ///
+  /// Get the string/binary value for a column by its index.
+  ///
+  /// These methods are faster than their name-based counterparts
+  /// since they use indices to avoid hashmap lookups, so index-based getters
+  /// should be preferred in performance-sensitive code.
+  ///
+  /// @param [in] col_index
+  ///   The index of the column.
+  /// @param [out] val
+  ///   Pointer to the placeholder to put the resulting value.
+  ///   Note that the method does not copy the value. Callers should copy
+  ///   the resulting Slice if necessary.
+  /// @return Operation result status. Return a bad Status if at least one
+  ///   of the following is @c true:
+  ///     @li The type does not match.
+  ///     @li The value is unset.
+  ///     @li The value is @c NULL.
+  ///
+  ///@{
+  Status GetString(int col_idx, Slice* val) const WARN_UNUSED_RESULT;
   Status GetBinary(int col_idx, Slice* val) const WARN_UNUSED_RESULT;
+  ///@}
 
   //------------------------------------------------------------
   // Key-encoding related functions
   //------------------------------------------------------------
 
-  // Encode a row key suitable for use as a tablet split key, an encoded
-  // key range, etc.
-  //
-  // Requires that all of the key columns must be set; otherwise, returns
-  // InvalidArgument.
+  /// Encode a row key.
+  ///
+  /// The result is suitable for use as a tablet split key, an encoded
+  /// key range, etc.
+  ///
+  /// @pre All of the key columns must be set.
+  ///
+  /// @param [out] encoded_key
+  ///   The encoded key (i.e. the result of the encoding).
+  /// @return Operation result status. In particular, this method returns
+  ///   InvalidArgument if not all the key columns are set.
   Status EncodeRowKey(std::string* encoded_key) const;
 
-  // Convenience method which is equivalent to the above, but triggers a
-  // FATAL error on failure.
+  /// Convenience method which is similar to EncodeRowKey.
+  ///
+  /// This is equivalent to the EncodeRowKey, but triggers a FATAL error
+  /// on failure.
+  ///
+  /// @return The encoded key.
   std::string ToEncodedRowKeyOrDie() const;
 
   //------------------------------------------------------------
   // Utility code
   //------------------------------------------------------------
 
-  // Return true if all of the key columns have been specified
-  // for this mutation.
+  /// @return @c true if all key column values have been set
+  ///   for this mutation.
   bool IsKeySet() const;
 
-  // Return true if all columns have been specified.
+  /// @return @c true if all column values have been set.
   bool AllColumnsSet() const;
 
+  /// @return String representation for the partial row.
   std::string ToString() const;
 
+  /// @return The schema object for the partial row.
   const Schema* schema() const { return schema_; }
 
  private:

http://git-wip-us.apache.org/repos/asf/kudu/blob/88fe33c9/src/kudu/util/monotime.h
----------------------------------------------------------------------
diff --git a/src/kudu/util/monotime.h b/src/kudu/util/monotime.h
index 25f3056..de1c1e9 100644
--- a/src/kudu/util/monotime.h
+++ b/src/kudu/util/monotime.h
@@ -36,37 +36,94 @@ struct timespec;
 namespace kudu {
 class MonoTime;
 
-// Represent an elapsed duration of time -- i.e the delta between
-// two MonoTime instances.
-//
-// A MonoDelta built with the default constructor is "uninitialized" and
-// may not be used for any operation.
+/// @brief A representation of a time interval.
+///
+/// The MonoDelta class represents an elapsed duration of time -- i.e.
+/// the delta between two MonoTime instances.
 class KUDU_EXPORT MonoDelta {
  public:
+  /// @name Converters from seconds representation (and ubiquitous SI prefixes).
+  ///
+  /// @param [in] seconds/ms/us/ns
+  ///   Time interval representation in seconds (with ubiquitous SI prefixes).
+  /// @return The resulting MonoDelta object initialized in accordance with
+  ///   the specified parameter.
+  ///
+  ///@{
   static MonoDelta FromSeconds(double seconds);
   static MonoDelta FromMilliseconds(int64_t ms);
   static MonoDelta FromMicroseconds(int64_t us);
   static MonoDelta FromNanoseconds(int64_t ns);
+  ///@}
+
+  /// Build a MonoDelta object.
+  ///
+  /// @note A MonoDelta instance built with the this default constructor is
+  ///   "uninitialized" and may not be used for any operation.
   MonoDelta();
+
+  /// @return @c true iff this object is initialized.
   bool Initialized() const;
+
+  /// Check whether this time interval is shorter than the specified one.
+  ///
+  /// @param [in] rhs
+  ///   A time interval for comparison.
+  /// @return @c true iff this time interval is strictly shorter
+  ///   than the specified one.
   bool LessThan(const MonoDelta &rhs) const;
+
+  /// Check whether this time interval is longer than the specified one.
+  ///
+  /// @param [in] rhs
+  ///   A time interval for comparison.
+  /// @return @c true iff this time interval is strictly longer
+  ///   than the specified one.
   bool MoreThan(const MonoDelta &rhs) const;
+
+  /// Check whether this time interval has the same duration
+  ///  as the specified one.
+  ///
+  /// @param [in] rhs
+  ///   A time interval for comparison.
+  /// @return @c true iff this time interval has the same duration as the
+  ///   the specified one.
   bool Equals(const MonoDelta &rhs) const;
+
+  /// @return String representation of this interval's duration (in seconds).
   std::string ToString() const;
+
+  /// @name Converters into seconds representation (and ubiquitous SI prefixes).
+  ///
+  /// @return Representation of the time interval in appropriate SI units.
+  ///
+  ///@{
   double ToSeconds() const;
   int64_t ToMilliseconds() const;
   int64_t ToMicroseconds() const;
   int64_t ToNanoseconds() const;
+  ///@}
 
-  // Update struct timeval to current value of delta, with microsecond accuracy.
-  // Note that if MonoDelta::IsPositive() returns true, the struct timeval
-  // is guaranteed to hold a positive number as well (at least 1 microsecond).
+  /// Represent this time interval as a timeval structure, with microsecond
+  /// accuracy.
+  ///
+  /// @param [out] tv
+  ///   Placeholder for the result value.
   void ToTimeVal(struct timeval *tv) const;
 
-  // Update struct timespec to current value of delta, with nanosecond accuracy.
+  /// Represent this time interval as a timespec structure, with nanosecond
+  /// accuracy.
+  ///
+  /// @param [out] ts
+  ///   Placeholder for the result value.
   void ToTimeSpec(struct timespec *ts) const;
 
-  // Convert a nanosecond value to a timespec.
+  /// Convert a nanosecond value to a timespec.
+  ///
+  /// @param [in] nanos
+  ///   Representation of a relative point in time in nanoseconds.
+  /// @param [out] ts
+  ///   Placeholder for the resulting timespec representation.
   static void NanosToTimeSpec(int64_t nanos, struct timespec* ts);
 
  private:
@@ -78,44 +135,97 @@ class KUDU_EXPORT MonoDelta {
   int64_t nano_delta_;
 };
 
-// Represent a particular point in time, relative to some fixed but unspecified
-// reference point.
-//
-// This time is monotonic, meaning that if the user changes his or her system
-// clock, the monotime does not change.
+/// @brief Representation of a particular point in time.
+///
+/// The MonoTime class represents a particular point in time,
+/// relative to some fixed but unspecified reference point.
+///
+/// This time is monotonic, meaning that if the user changes his or her system
+/// clock, the monotime does not change.
 class KUDU_EXPORT MonoTime {
  public:
+  /// @brief The granularity of the time specification
+  ///
+  /// The coarse monotonic time is faster to retrieve, but "only"
+  /// accurate to within a millisecond or two. The speed difference will
+  /// depend on your timer hardware.
   enum Granularity {
     COARSE,
     FINE
   };
 
+  /// @name Conversion constants for ubiquitous time units.
+  ///
+  ///@{
   static const int64_t kNanosecondsPerSecond = 1000000000L;
   static const int64_t kNanosecondsPerMillisecond = 1000000L;
   static const int64_t kNanosecondsPerMicrosecond = 1000L;
 
   static const int64_t kMicrosecondsPerSecond = 1000000L;
+  ///@}
 
-  // The coarse monotonic time is faster to retrieve, but "only"
-  // accurate to within a millisecond or two.  The speed difference will
-  // depend on your timer hardware.
+  /// Get current time in MonoTime representation.
+  ///
+  /// @param [in] granularity
+  ///   Granularity for the resulting time specification.
+  /// @return Time specification for the moment of the method's invocation.
   static MonoTime Now(enum Granularity granularity);
 
-  // Return MonoTime equal to farthest possible time into the future.
+  /// @return MonoTime equal to farthest possible time into the future.
   static MonoTime Max();
 
-  // Return MonoTime equal to farthest possible time into the past.
+  /// @return MonoTime equal to farthest possible time into the past.
   static MonoTime Min();
 
-  // Return the earliest (minimum) of the two monotimes.
+  /// Select the earliest between the specified time points.
+  ///
+  /// @param [in] a
+  ///   The first MonoTime object to select from.
+  /// @param [in] b
+  ///   The second MonoTime object to select from.
+  /// @return The earliest (minimum) of the two monotimes.
   static const MonoTime& Earliest(const MonoTime& a, const MonoTime& b);
 
+  /// Build a MonoTime object. The resulting object is not initialized
+  /// and not ready to use.
   MonoTime();
+
+  /// @return @c true iff the object is initialized.
   bool Initialized() const;
+
+  /// Compute time interval between the point in time specified by this
+  /// and the specified object.
+  ///
+  /// @param [in] rhs
+  ///   The object that corresponds to the left boundary of the time interval,
+  ///   where this object corresponds to the right boundary of the interval.
+  /// @return The resulting time interval represented as a MonoDelta object.
   MonoDelta GetDeltaSince(const MonoTime &rhs) const;
+
+  /// Advance this object's time specification by the specified interval.
+  ///
+  /// @param [in] delta
+  ///   The time interval to add.
   void AddDelta(const MonoDelta &delta);
+
+  /// Check whether the point in time specified by this object is earlier
+  /// than the specified one.
+  ///
+  /// @param [in] rhs
+  ///   The other MonoTime object to compare with.
+  /// @return @c true iff the point in time represented by this MonoTime object
+  ///   is earlier then the point in time represented by the parameter.
   bool ComesBefore(const MonoTime &rhs) const;
+
+  /// @return String representation of the object (in seconds).
   std::string ToString() const;
+
+  /// Check whether this object represents the same point in time as the other.
+  ///
+  /// @param [in] other
+  ///   The other MonoTime object to compare.
+  /// @return @c true iff the point in time represented by this MonoTime object
+  ///   is the same as the one represented by the other.
   bool Equals(const MonoTime& other) const;
 
  private:
@@ -129,11 +239,16 @@ class KUDU_EXPORT MonoTime {
   uint64_t nanos_;
 };
 
-// Sleep for a MonoDelta duration.
-//
-// This is preferred over sleep(3), usleep(3), and nanosleep(3). It's less prone to mixups with
-// units since it uses a MonoDelta. It also ignores EINTR, so will reliably sleep at least the
-// MonoDelta duration.
+/// Sleep for an interval specified by a MonoDelta instance.
+///
+/// This is preferred over sleep(3), usleep(3), and nanosleep(3).
+/// It's less prone to mixups with units since it uses the MonoDelta for
+/// interval specification.
+/// Besides, it ignores signals/EINTR, so will reliably sleep at least for the
+/// MonoDelta duration.
+///
+/// @param [in] delta
+///   The time interval to sleep for.
 void KUDU_EXPORT SleepFor(const MonoDelta& delta);
 
 } // namespace kudu


Mime
View raw message