You are viewing a plain text version of this content. The canonical link for it is here.
Posted to github@arrow.apache.org by "js8544 (via GitHub)" <gi...@apache.org> on 2023/05/26 16:38:59 UTC

[GitHub] [arrow] js8544 opened a new pull request, #35794: GH-35618: [C++][Doc] Improve doc for Datum

js8544 opened a new pull request, #35794:
URL: https://github.com/apache/arrow/pull/35794

   Improve doc for `Datum` to avoid confusion as documented in the coresponding issue.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [arrow] pitrou commented on a diff in pull request #35794: GH-35618: [C++][Doc] Improve doc for Datum

Posted by "pitrou (via GitHub)" <gi...@apache.org>.
pitrou commented on code in PR #35794:
URL: https://github.com/apache/arrow/pull/35794#discussion_r1210615490


##########
cpp/src/arrow/datum.h:
##########
@@ -146,6 +183,8 @@ struct ARROW_EXPORT Datum {
     }
   }
 
+  /// \brief Retrieve the stored array as ArrayData, use make_array() if Array is desired

Review Comment:
   ```suggestion
     /// \brief Retrieve the stored array as ArrayData
     /// 
     /// Use make_array() if an Array is desired (which is more expensive).
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [arrow] pitrou commented on a diff in pull request #35794: GH-35618: [C++][Doc] Improve doc for Datum

Posted by "pitrou (via GitHub)" <gi...@apache.org>.
pitrou commented on code in PR #35794:
URL: https://github.com/apache/arrow/pull/35794#discussion_r1210619100


##########
cpp/src/arrow/datum.h:
##########
@@ -220,11 +284,13 @@ struct ARROW_EXPORT Datum {
   /// \return empty if not arraylike
   ArrayVector chunks() const;
 
+  /// \brief True if the two data are equal
   bool Equals(const Datum& other) const;
 
   bool operator==(const Datum& other) const { return Equals(other); }
   bool operator!=(const Datum& other) const { return !Equals(other); }
 
+  /// \brief Print the kind of datum stored

Review Comment:
   ```suggestion
     /// \brief Return a string representation of the kind of datum stored.
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [arrow] js8544 commented on a diff in pull request #35794: GH-35618: [C++][Doc] Improve doc for Datum

Posted by "js8544 (via GitHub)" <gi...@apache.org>.
js8544 commented on code in PR #35794:
URL: https://github.com/apache/arrow/pull/35794#discussion_r1211038581


##########
cpp/src/arrow/datum.h:
##########
@@ -64,69 +68,102 @@ struct ARROW_EXPORT Datum {
   Datum(Datum&& other) = default;
   Datum& operator=(Datum&& other) = default;
 
+  /// \brief Construct from a Scalar
   Datum(std::shared_ptr<Scalar> value)  // NOLINT implicit conversion
       : value(std::move(value)) {}
 
+  /// \brief Construct from an ArrayData
   Datum(std::shared_ptr<ArrayData> value)  // NOLINT implicit conversion
       : value(std::move(value)) {}
 
+  /// \brief Construct from an ArrayData
   Datum(ArrayData arg)  // NOLINT implicit conversion
       : value(std::make_shared<ArrayData>(std::move(arg))) {}
 
-  Datum(const Array& value);                   // NOLINT implicit conversion
+  /// \brief Construct from an Array
+  Datum(const Array& value);  // NOLINT implicit conversion
+
+  /// \brief Construct from an Array
   Datum(const std::shared_ptr<Array>& value);  // NOLINT implicit conversion
+
+  /// \brief Construct from a ChunkedArray
   Datum(std::shared_ptr<ChunkedArray> value);  // NOLINT implicit conversion
-  Datum(std::shared_ptr<RecordBatch> value);   // NOLINT implicit conversion
-  Datum(std::shared_ptr<Table> value);         // NOLINT implicit conversion
 
-  // Explicit constructors from const-refs. Can be expensive, prefer the
-  // shared_ptr constructors
+  /// \brief Construct from a RecordBatch
+  Datum(std::shared_ptr<RecordBatch> value);  // NOLINT implicit conversion
+
+  /// \brief Construct from a Table
+  Datum(std::shared_ptr<Table> value);  // NOLINT implicit conversion
+
+  /// \brief Construct from a ChunkedArray. Can be expensive, prefer the
+  /// shared_ptr constructor
   explicit Datum(const ChunkedArray& value);
+
+  /// \brief Construct from a RecordBatch. Can be expensive, prefer the
+  /// shared_ptr constructor
   explicit Datum(const RecordBatch& value);
+
+  /// \brief Construct from a Table. Can be expensive, prefer the
+  /// shared_ptr constructor
   explicit Datum(const Table& value);
 
-  // Cast from subtypes of Array or Scalar to Datum
+  /// \brief Cast from concrete types of Array or Scalar to Datum

Review Comment:
   done



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [arrow] github-actions[bot] commented on pull request #35794: GH-35618: [C++][Doc] Improve doc for Datum

Posted by "github-actions[bot] (via GitHub)" <gi...@apache.org>.
github-actions[bot] commented on PR #35794:
URL: https://github.com/apache/arrow/pull/35794#issuecomment-1564650569

   * Closes: #35618


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [arrow] pitrou commented on a diff in pull request #35794: GH-35618: [C++][Doc] Improve doc for Datum

Posted by "pitrou (via GitHub)" <gi...@apache.org>.
pitrou commented on code in PR #35794:
URL: https://github.com/apache/arrow/pull/35794#discussion_r1210617389


##########
cpp/src/arrow/datum.h:
##########
@@ -155,49 +194,74 @@ struct ARROW_EXPORT Datum {
   /// \see arrow::util::TotalBufferSize for caveats
   int64_t TotalBufferSize() const;
 
+  /// \brief Get the stored ArrayData in mutable form, primarily used in kernel
+  /// implementations

Review Comment:
   ```suggestion
     /// \brief Get the stored ArrayData in mutable form
     /// 
     /// For internal use primarily. Keep in mind a shared_ptr<Datum> may have multiple owners.
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [arrow] pitrou commented on a diff in pull request #35794: GH-35618: [C++][Doc] Improve doc for Datum

Posted by "pitrou (via GitHub)" <gi...@apache.org>.
pitrou commented on code in PR #35794:
URL: https://github.com/apache/arrow/pull/35794#discussion_r1210613957


##########
cpp/src/arrow/datum.h:
##########
@@ -64,69 +68,102 @@ struct ARROW_EXPORT Datum {
   Datum(Datum&& other) = default;
   Datum& operator=(Datum&& other) = default;
 
+  /// \brief Construct from a Scalar
   Datum(std::shared_ptr<Scalar> value)  // NOLINT implicit conversion
       : value(std::move(value)) {}
 
+  /// \brief Construct from an ArrayData
   Datum(std::shared_ptr<ArrayData> value)  // NOLINT implicit conversion
       : value(std::move(value)) {}
 
+  /// \brief Construct from an ArrayData
   Datum(ArrayData arg)  // NOLINT implicit conversion
       : value(std::make_shared<ArrayData>(std::move(arg))) {}
 
-  Datum(const Array& value);                   // NOLINT implicit conversion
+  /// \brief Construct from an Array
+  Datum(const Array& value);  // NOLINT implicit conversion
+
+  /// \brief Construct from an Array
   Datum(const std::shared_ptr<Array>& value);  // NOLINT implicit conversion
+
+  /// \brief Construct from a ChunkedArray
   Datum(std::shared_ptr<ChunkedArray> value);  // NOLINT implicit conversion
-  Datum(std::shared_ptr<RecordBatch> value);   // NOLINT implicit conversion
-  Datum(std::shared_ptr<Table> value);         // NOLINT implicit conversion
 
-  // Explicit constructors from const-refs. Can be expensive, prefer the
-  // shared_ptr constructors
+  /// \brief Construct from a RecordBatch
+  Datum(std::shared_ptr<RecordBatch> value);  // NOLINT implicit conversion
+
+  /// \brief Construct from a Table
+  Datum(std::shared_ptr<Table> value);  // NOLINT implicit conversion
+
+  /// \brief Construct from a ChunkedArray. Can be expensive, prefer the
+  /// shared_ptr constructor
   explicit Datum(const ChunkedArray& value);
+
+  /// \brief Construct from a RecordBatch. Can be expensive, prefer the
+  /// shared_ptr constructor
   explicit Datum(const RecordBatch& value);
+
+  /// \brief Construct from a Table. Can be expensive, prefer the
+  /// shared_ptr constructor
   explicit Datum(const Table& value);
 
-  // Cast from subtypes of Array or Scalar to Datum
+  /// \brief Cast from concrete types of Array or Scalar to Datum
   template <typename T, bool IsArray = std::is_base_of_v<Array, T>,
             bool IsScalar = std::is_base_of_v<Scalar, T>,
             typename = enable_if_t<IsArray || IsScalar>>
   Datum(std::shared_ptr<T> value)  // NOLINT implicit conversion
       : Datum(std::shared_ptr<typename std::conditional<IsArray, Array, Scalar>::type>(
             std::move(value))) {}
 
-  // Cast from subtypes of Array or Scalar to Datum
+  /// \brief Cast from concrete types of Array or Scalar to Datum
   template <typename T, typename TV = typename std::remove_reference_t<T>,
             bool IsArray = std::is_base_of_v<Array, T>,
             bool IsScalar = std::is_base_of_v<Scalar, T>,
             typename = enable_if_t<IsArray || IsScalar>>
   Datum(T&& value)  // NOLINT implicit conversion
       : Datum(std::make_shared<TV>(std::forward<T>(value))) {}
 
-  // Many Scalars are copyable, let that happen
+  /// \brief Copy from concrete types of Scalar. The scalar type must copyable.
   template <typename T, typename = enable_if_t<std::is_base_of_v<Scalar, T>>>
   Datum(const T& value)  // NOLINT implicit conversion
       : Datum(std::make_shared<T>(value)) {}
 
   // Convenience constructors
+  /// \brief A convenience constructor. Stores a bool scalar.

Review Comment:
   ```suggestion
     /// \brief Convenience constructor storing a bool scalar.
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [arrow] pitrou commented on a diff in pull request #35794: GH-35618: [C++][Doc] Improve doc for Datum

Posted by "pitrou (via GitHub)" <gi...@apache.org>.
pitrou commented on code in PR #35794:
URL: https://github.com/apache/arrow/pull/35794#discussion_r1210612767


##########
cpp/src/arrow/datum.h:
##########
@@ -64,69 +68,102 @@ struct ARROW_EXPORT Datum {
   Datum(Datum&& other) = default;
   Datum& operator=(Datum&& other) = default;
 
+  /// \brief Construct from a Scalar
   Datum(std::shared_ptr<Scalar> value)  // NOLINT implicit conversion
       : value(std::move(value)) {}
 
+  /// \brief Construct from an ArrayData
   Datum(std::shared_ptr<ArrayData> value)  // NOLINT implicit conversion
       : value(std::move(value)) {}
 
+  /// \brief Construct from an ArrayData
   Datum(ArrayData arg)  // NOLINT implicit conversion
       : value(std::make_shared<ArrayData>(std::move(arg))) {}
 
-  Datum(const Array& value);                   // NOLINT implicit conversion
+  /// \brief Construct from an Array
+  Datum(const Array& value);  // NOLINT implicit conversion
+
+  /// \brief Construct from an Array
   Datum(const std::shared_ptr<Array>& value);  // NOLINT implicit conversion
+
+  /// \brief Construct from a ChunkedArray
   Datum(std::shared_ptr<ChunkedArray> value);  // NOLINT implicit conversion
-  Datum(std::shared_ptr<RecordBatch> value);   // NOLINT implicit conversion
-  Datum(std::shared_ptr<Table> value);         // NOLINT implicit conversion
 
-  // Explicit constructors from const-refs. Can be expensive, prefer the
-  // shared_ptr constructors
+  /// \brief Construct from a RecordBatch
+  Datum(std::shared_ptr<RecordBatch> value);  // NOLINT implicit conversion
+
+  /// \brief Construct from a Table
+  Datum(std::shared_ptr<Table> value);  // NOLINT implicit conversion
+
+  /// \brief Construct from a ChunkedArray. Can be expensive, prefer the
+  /// shared_ptr constructor
   explicit Datum(const ChunkedArray& value);
+
+  /// \brief Construct from a RecordBatch. Can be expensive, prefer the
+  /// shared_ptr constructor

Review Comment:
   (same kind of suggestion here and below)



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [arrow] pitrou commented on a diff in pull request #35794: GH-35618: [C++][Doc] Improve doc for Datum

Posted by "pitrou (via GitHub)" <gi...@apache.org>.
pitrou commented on code in PR #35794:
URL: https://github.com/apache/arrow/pull/35794#discussion_r1210614873


##########
cpp/src/arrow/datum.h:
##########
@@ -64,69 +68,102 @@ struct ARROW_EXPORT Datum {
   Datum(Datum&& other) = default;
   Datum& operator=(Datum&& other) = default;
 
+  /// \brief Construct from a Scalar
   Datum(std::shared_ptr<Scalar> value)  // NOLINT implicit conversion
       : value(std::move(value)) {}
 
+  /// \brief Construct from an ArrayData
   Datum(std::shared_ptr<ArrayData> value)  // NOLINT implicit conversion
       : value(std::move(value)) {}
 
+  /// \brief Construct from an ArrayData
   Datum(ArrayData arg)  // NOLINT implicit conversion
       : value(std::make_shared<ArrayData>(std::move(arg))) {}
 
-  Datum(const Array& value);                   // NOLINT implicit conversion
+  /// \brief Construct from an Array
+  Datum(const Array& value);  // NOLINT implicit conversion
+
+  /// \brief Construct from an Array
   Datum(const std::shared_ptr<Array>& value);  // NOLINT implicit conversion
+
+  /// \brief Construct from a ChunkedArray
   Datum(std::shared_ptr<ChunkedArray> value);  // NOLINT implicit conversion
-  Datum(std::shared_ptr<RecordBatch> value);   // NOLINT implicit conversion
-  Datum(std::shared_ptr<Table> value);         // NOLINT implicit conversion
 
-  // Explicit constructors from const-refs. Can be expensive, prefer the
-  // shared_ptr constructors
+  /// \brief Construct from a RecordBatch
+  Datum(std::shared_ptr<RecordBatch> value);  // NOLINT implicit conversion
+
+  /// \brief Construct from a Table
+  Datum(std::shared_ptr<Table> value);  // NOLINT implicit conversion
+
+  /// \brief Construct from a ChunkedArray. Can be expensive, prefer the
+  /// shared_ptr constructor
   explicit Datum(const ChunkedArray& value);
+
+  /// \brief Construct from a RecordBatch. Can be expensive, prefer the
+  /// shared_ptr constructor
   explicit Datum(const RecordBatch& value);
+
+  /// \brief Construct from a Table. Can be expensive, prefer the
+  /// shared_ptr constructor
   explicit Datum(const Table& value);
 
-  // Cast from subtypes of Array or Scalar to Datum
+  /// \brief Cast from concrete types of Array or Scalar to Datum
   template <typename T, bool IsArray = std::is_base_of_v<Array, T>,
             bool IsScalar = std::is_base_of_v<Scalar, T>,
             typename = enable_if_t<IsArray || IsScalar>>
   Datum(std::shared_ptr<T> value)  // NOLINT implicit conversion
       : Datum(std::shared_ptr<typename std::conditional<IsArray, Array, Scalar>::type>(
             std::move(value))) {}
 
-  // Cast from subtypes of Array or Scalar to Datum
+  /// \brief Cast from concrete types of Array or Scalar to Datum
   template <typename T, typename TV = typename std::remove_reference_t<T>,
             bool IsArray = std::is_base_of_v<Array, T>,
             bool IsScalar = std::is_base_of_v<Scalar, T>,
             typename = enable_if_t<IsArray || IsScalar>>
   Datum(T&& value)  // NOLINT implicit conversion
       : Datum(std::make_shared<TV>(std::forward<T>(value))) {}
 
-  // Many Scalars are copyable, let that happen
+  /// \brief Copy from concrete types of Scalar. The scalar type must copyable.
   template <typename T, typename = enable_if_t<std::is_base_of_v<Scalar, T>>>
   Datum(const T& value)  // NOLINT implicit conversion
       : Datum(std::make_shared<T>(value)) {}
 
   // Convenience constructors
+  /// \brief A convenience constructor. Stores a bool scalar.
   explicit Datum(bool value);
+  /// \brief A convenience constructor. Stores a int8 scalar.
   explicit Datum(int8_t value);
+  /// \brief A convenience constructor. Stores a uint8 scalar.
   explicit Datum(uint8_t value);
+  /// \brief A convenience constructor. Stores a int16 scalar.
   explicit Datum(int16_t value);
+  /// \brief A convenience constructor. Stores a uint16 scalar.
   explicit Datum(uint16_t value);
+  /// \brief A convenience constructor. Stores a int32 scalar.
   explicit Datum(int32_t value);
+  /// \brief A convenience constructor. Stores a uint32 scalar.
   explicit Datum(uint32_t value);
+  /// \brief A convenience constructor. Stores a int64 scalar.
   explicit Datum(int64_t value);
+  /// \brief A convenience constructor. Stores a uint64 scalar.
   explicit Datum(uint64_t value);
+  /// \brief A convenience constructor. Stores a float scalar.
   explicit Datum(float value);
+  /// \brief A convenience constructor. Stores a double scalar.
   explicit Datum(double value);
+  /// \brief A convenience constructor. Stores a string scalar.
   explicit Datum(std::string value);
+  /// \brief A convenience constructor. Stores a string scalar.
   explicit Datum(const char* value);
 
-  // Forward to convenience constructors for a DurationScalar from std::chrono::duration
+  /// \brief Forward to convenience constructors for a DurationScalar from
+  /// std::chrono::duration

Review Comment:
   The fact that it forwards is more of an implementation detail:
   ```suggestion
     /// \brief Convenience constructor for a DurationScalar from std::chrono::duration
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [arrow] ursabot commented on pull request #35794: GH-35618: [C++][Doc] Improve doc for Datum

Posted by "ursabot (via GitHub)" <gi...@apache.org>.
ursabot commented on PR #35794:
URL: https://github.com/apache/arrow/pull/35794#issuecomment-1572181016

   Benchmark runs are scheduled for baseline = d9c2d5961766d16fa0cae3b0ba9b2335ffd6bdb6 and contender = cbc17a98dfd9fb660523f61ecd361b157d278372. cbc17a98dfd9fb660523f61ecd361b157d278372 is a master commit associated with this PR. Results will be available as each benchmark for each run completes.
   Conbench compare runs links:
   [Finished :arrow_down:0.0% :arrow_up:0.0%] [ec2-t3-xlarge-us-east-2](https://conbench.ursa.dev/compare/runs/c97af4cac1cb4e3798dfd647e0220e3b...b68f8941916b4d23b32c378db96d226f/)
   [Finished :arrow_down:2.33% :arrow_up:0.18%] [test-mac-arm](https://conbench.ursa.dev/compare/runs/1a6be6058ee24142ab813beb36fb8d8a...d6251aea6aa443958773d9df82c8306f/)
   [Finished :arrow_down:0.33% :arrow_up:0.0%] [ursa-i9-9960x](https://conbench.ursa.dev/compare/runs/e8ffb3d5748442d796e3f2b607cb5456...b0515c2eead642d591753d5fd90cb299/)
   [Finished :arrow_down:0.48% :arrow_up:0.27%] [ursa-thinkcentre-m75q](https://conbench.ursa.dev/compare/runs/09b9966884654197acb47570e2ea84e6...91458747cc1648309bf465c6b9a2af13/)
   Buildkite builds:
   [Finished] [`cbc17a98` ec2-t3-xlarge-us-east-2](https://buildkite.com/apache-arrow/arrow-bci-benchmark-on-ec2-t3-xlarge-us-east-2/builds/2960)
   [Finished] [`cbc17a98` test-mac-arm](https://buildkite.com/apache-arrow/arrow-bci-benchmark-on-test-mac-arm/builds/2996)
   [Finished] [`cbc17a98` ursa-i9-9960x](https://buildkite.com/apache-arrow/arrow-bci-benchmark-on-ursa-i9-9960x/builds/2961)
   [Finished] [`cbc17a98` ursa-thinkcentre-m75q](https://buildkite.com/apache-arrow/arrow-bci-benchmark-on-ursa-thinkcentre-m75q/builds/2986)
   [Finished] [`d9c2d596` ec2-t3-xlarge-us-east-2](https://buildkite.com/apache-arrow/arrow-bci-benchmark-on-ec2-t3-xlarge-us-east-2/builds/2959)
   [Finished] [`d9c2d596` test-mac-arm](https://buildkite.com/apache-arrow/arrow-bci-benchmark-on-test-mac-arm/builds/2995)
   [Finished] [`d9c2d596` ursa-i9-9960x](https://buildkite.com/apache-arrow/arrow-bci-benchmark-on-ursa-i9-9960x/builds/2960)
   [Finished] [`d9c2d596` ursa-thinkcentre-m75q](https://buildkite.com/apache-arrow/arrow-bci-benchmark-on-ursa-thinkcentre-m75q/builds/2985)
   Supported benchmarks:
   ec2-t3-xlarge-us-east-2: Supported benchmark langs: Python, R. Runs only benchmarks with cloud = True
   test-mac-arm: Supported benchmark langs: C++, Python, R
   ursa-i9-9960x: Supported benchmark langs: Python, R, JavaScript
   ursa-thinkcentre-m75q: Supported benchmark langs: C++, Java
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [arrow] pitrou commented on a diff in pull request #35794: GH-35618: [C++][Doc] Improve doc for Datum

Posted by "pitrou (via GitHub)" <gi...@apache.org>.
pitrou commented on code in PR #35794:
URL: https://github.com/apache/arrow/pull/35794#discussion_r1210613034


##########
cpp/src/arrow/datum.h:
##########
@@ -64,69 +68,102 @@ struct ARROW_EXPORT Datum {
   Datum(Datum&& other) = default;
   Datum& operator=(Datum&& other) = default;
 
+  /// \brief Construct from a Scalar
   Datum(std::shared_ptr<Scalar> value)  // NOLINT implicit conversion
       : value(std::move(value)) {}
 
+  /// \brief Construct from an ArrayData
   Datum(std::shared_ptr<ArrayData> value)  // NOLINT implicit conversion
       : value(std::move(value)) {}
 
+  /// \brief Construct from an ArrayData
   Datum(ArrayData arg)  // NOLINT implicit conversion
       : value(std::make_shared<ArrayData>(std::move(arg))) {}
 
-  Datum(const Array& value);                   // NOLINT implicit conversion
+  /// \brief Construct from an Array
+  Datum(const Array& value);  // NOLINT implicit conversion
+
+  /// \brief Construct from an Array
   Datum(const std::shared_ptr<Array>& value);  // NOLINT implicit conversion
+
+  /// \brief Construct from a ChunkedArray
   Datum(std::shared_ptr<ChunkedArray> value);  // NOLINT implicit conversion
-  Datum(std::shared_ptr<RecordBatch> value);   // NOLINT implicit conversion
-  Datum(std::shared_ptr<Table> value);         // NOLINT implicit conversion
 
-  // Explicit constructors from const-refs. Can be expensive, prefer the
-  // shared_ptr constructors
+  /// \brief Construct from a RecordBatch
+  Datum(std::shared_ptr<RecordBatch> value);  // NOLINT implicit conversion
+
+  /// \brief Construct from a Table
+  Datum(std::shared_ptr<Table> value);  // NOLINT implicit conversion
+
+  /// \brief Construct from a ChunkedArray. Can be expensive, prefer the
+  /// shared_ptr constructor
   explicit Datum(const ChunkedArray& value);
+
+  /// \brief Construct from a RecordBatch. Can be expensive, prefer the
+  /// shared_ptr constructor
   explicit Datum(const RecordBatch& value);
+
+  /// \brief Construct from a Table. Can be expensive, prefer the
+  /// shared_ptr constructor
   explicit Datum(const Table& value);
 
-  // Cast from subtypes of Array or Scalar to Datum
+  /// \brief Cast from concrete types of Array or Scalar to Datum

Review Comment:
   "subtypes" rather than "types"?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [arrow] pitrou commented on a diff in pull request #35794: GH-35618: [C++][Doc] Improve doc for Datum

Posted by "pitrou (via GitHub)" <gi...@apache.org>.
pitrou commented on code in PR #35794:
URL: https://github.com/apache/arrow/pull/35794#discussion_r1210612587


##########
cpp/src/arrow/datum.h:
##########
@@ -64,69 +68,102 @@ struct ARROW_EXPORT Datum {
   Datum(Datum&& other) = default;
   Datum& operator=(Datum&& other) = default;
 
+  /// \brief Construct from a Scalar
   Datum(std::shared_ptr<Scalar> value)  // NOLINT implicit conversion
       : value(std::move(value)) {}
 
+  /// \brief Construct from an ArrayData
   Datum(std::shared_ptr<ArrayData> value)  // NOLINT implicit conversion
       : value(std::move(value)) {}
 
+  /// \brief Construct from an ArrayData
   Datum(ArrayData arg)  // NOLINT implicit conversion
       : value(std::make_shared<ArrayData>(std::move(arg))) {}
 
-  Datum(const Array& value);                   // NOLINT implicit conversion
+  /// \brief Construct from an Array
+  Datum(const Array& value);  // NOLINT implicit conversion
+
+  /// \brief Construct from an Array
   Datum(const std::shared_ptr<Array>& value);  // NOLINT implicit conversion
+
+  /// \brief Construct from a ChunkedArray
   Datum(std::shared_ptr<ChunkedArray> value);  // NOLINT implicit conversion
-  Datum(std::shared_ptr<RecordBatch> value);   // NOLINT implicit conversion
-  Datum(std::shared_ptr<Table> value);         // NOLINT implicit conversion
 
-  // Explicit constructors from const-refs. Can be expensive, prefer the
-  // shared_ptr constructors
+  /// \brief Construct from a RecordBatch
+  Datum(std::shared_ptr<RecordBatch> value);  // NOLINT implicit conversion
+
+  /// \brief Construct from a Table
+  Datum(std::shared_ptr<Table> value);  // NOLINT implicit conversion
+
+  /// \brief Construct from a ChunkedArray. Can be expensive, prefer the
+  /// shared_ptr constructor

Review Comment:
   ```suggestion
     /// \brief Construct from a ChunkedArray.
     ///
     /// This can be expensive, prefer the shared_ptr<ChunkedArray> constructor
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [arrow] pitrou commented on pull request #35794: GH-35618: [C++][Doc] Improve doc for Datum

Posted by "pitrou (via GitHub)" <gi...@apache.org>.
pitrou commented on PR #35794:
URL: https://github.com/apache/arrow/pull/35794#issuecomment-1568834471

   Thanks for doing this @js8544 ! I posted some small suggestions for style and accuracy.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [arrow] github-actions[bot] commented on pull request #35794: GH-35618: [C++][Doc] Improve doc for Datum

Posted by "github-actions[bot] (via GitHub)" <gi...@apache.org>.
github-actions[bot] commented on PR #35794:
URL: https://github.com/apache/arrow/pull/35794#issuecomment-1564650603

   :warning: GitHub issue #35618 **has been automatically assigned in GitHub** to PR creator.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [arrow] js8544 commented on pull request #35794: GH-35618: [C++][Doc] Improve doc for Datum

Posted by "js8544 (via GitHub)" <gi...@apache.org>.
js8544 commented on PR #35794:
URL: https://github.com/apache/arrow/pull/35794#issuecomment-1569433296

   > Thanks for doing this @js8544 ! I posted some small suggestions for style and accuracy.
   
   Thanks for the feedback! I've updated the doc.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [arrow] pitrou merged pull request #35794: GH-35618: [C++][Doc] Improve doc for Datum

Posted by "pitrou (via GitHub)" <gi...@apache.org>.
pitrou merged PR #35794:
URL: https://github.com/apache/arrow/pull/35794


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [arrow] pitrou commented on a diff in pull request #35794: GH-35618: [C++][Doc] Improve doc for Datum

Posted by "pitrou (via GitHub)" <gi...@apache.org>.
pitrou commented on code in PR #35794:
URL: https://github.com/apache/arrow/pull/35794#discussion_r1210618414


##########
cpp/src/arrow/datum.h:
##########
@@ -155,49 +194,74 @@ struct ARROW_EXPORT Datum {
   /// \see arrow::util::TotalBufferSize for caveats
   int64_t TotalBufferSize() const;
 
+  /// \brief Get the stored ArrayData in mutable form, primarily used in kernel
+  /// implementations
   ArrayData* mutable_array() const { return this->array().get(); }
 
+  /// \brief Retrieve the stored array as Array
+  /// \throws std::bad_variant_access if the datum is not an array
   std::shared_ptr<Array> make_array() const;
 
+  /// \brief Retrieve the chunked array stored
+  /// \throws std::bad_variant_access if the datum is not a chunked array
   const std::shared_ptr<ChunkedArray>& chunked_array() const {
     return std::get<std::shared_ptr<ChunkedArray>>(this->value);
   }
 
+  /// \brief Retrieve the record batch stored
+  /// \throws std::bad_variant_access if the datum is not a record batch
   const std::shared_ptr<RecordBatch>& record_batch() const {
     return std::get<std::shared_ptr<RecordBatch>>(this->value);
   }
 
+  /// \brief Retrieve the table stored
+  /// \throws std::bad_variant_access if the datum is not a table
   const std::shared_ptr<Table>& table() const {
     return std::get<std::shared_ptr<Table>>(this->value);
   }
 
+  /// \brief Retrieve the scalar stored
+  /// \throws std::bad_variant_access if the datum is not a scalar
   const std::shared_ptr<Scalar>& scalar() const {
     return std::get<std::shared_ptr<Scalar>>(this->value);
   }
 
+  /// \brief Retrieve the datum as its concrete array type
+  /// \throws std::bad_variant_access if the datum is not an array
+  /// \tparam ExactType the expected array type, may cause undefined behavior if it is not
+  /// the type of the stored array
   template <typename ExactType>
   std::shared_ptr<ExactType> array_as() const {
     return internal::checked_pointer_cast<ExactType>(this->make_array());
   }
 
+  /// \brief Retrieve the datum as its concrete scalar type
+  /// \throws std::bad_variant_access if the datum is not a scalar
+  /// \tparam ExactType the expected scalar type, may cause undefined behavior if it is
+  /// not the type of the stored scalar
   template <typename ExactType>
   const ExactType& scalar_as() const {
     return internal::checked_cast<const ExactType&>(*this->scalar());
   }
 
+  /// \brief True if Datum contains an array
   bool is_array() const { return this->kind() == Datum::ARRAY; }
 
+  /// \brief True if Datum contains a chunked array
   bool is_chunked_array() const { return this->kind() == Datum::CHUNKED_ARRAY; }
 
+  /// \brief True if Datum contains an array or a chunked array
   bool is_arraylike() const {
     return this->kind() == Datum::ARRAY || this->kind() == Datum::CHUNKED_ARRAY;
   }
 
+  /// \brief True if Datum contains a scalar
   bool is_scalar() const { return this->kind() == Datum::SCALAR; }
 
   /// \brief True if Datum contains a scalar or array-like data
   bool is_value() const { return this->is_arraylike() || this->is_scalar(); }
 
+  /// \brief Returns the null count. Only valid for scalar and array-like data

Review Comment:
   ```suggestion
     /// \brief Return the null count.
     ///
     /// Only valid for scalar and array-like data.
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [arrow] pitrou commented on a diff in pull request #35794: GH-35618: [C++][Doc] Improve doc for Datum

Posted by "pitrou (via GitHub)" <gi...@apache.org>.
pitrou commented on code in PR #35794:
URL: https://github.com/apache/arrow/pull/35794#discussion_r1210613622


##########
cpp/src/arrow/datum.h:
##########
@@ -64,69 +68,102 @@ struct ARROW_EXPORT Datum {
   Datum(Datum&& other) = default;
   Datum& operator=(Datum&& other) = default;
 
+  /// \brief Construct from a Scalar
   Datum(std::shared_ptr<Scalar> value)  // NOLINT implicit conversion
       : value(std::move(value)) {}
 
+  /// \brief Construct from an ArrayData
   Datum(std::shared_ptr<ArrayData> value)  // NOLINT implicit conversion
       : value(std::move(value)) {}
 
+  /// \brief Construct from an ArrayData
   Datum(ArrayData arg)  // NOLINT implicit conversion
       : value(std::make_shared<ArrayData>(std::move(arg))) {}
 
-  Datum(const Array& value);                   // NOLINT implicit conversion
+  /// \brief Construct from an Array
+  Datum(const Array& value);  // NOLINT implicit conversion
+
+  /// \brief Construct from an Array
   Datum(const std::shared_ptr<Array>& value);  // NOLINT implicit conversion
+
+  /// \brief Construct from a ChunkedArray
   Datum(std::shared_ptr<ChunkedArray> value);  // NOLINT implicit conversion
-  Datum(std::shared_ptr<RecordBatch> value);   // NOLINT implicit conversion
-  Datum(std::shared_ptr<Table> value);         // NOLINT implicit conversion
 
-  // Explicit constructors from const-refs. Can be expensive, prefer the
-  // shared_ptr constructors
+  /// \brief Construct from a RecordBatch
+  Datum(std::shared_ptr<RecordBatch> value);  // NOLINT implicit conversion
+
+  /// \brief Construct from a Table
+  Datum(std::shared_ptr<Table> value);  // NOLINT implicit conversion
+
+  /// \brief Construct from a ChunkedArray. Can be expensive, prefer the
+  /// shared_ptr constructor
   explicit Datum(const ChunkedArray& value);
+
+  /// \brief Construct from a RecordBatch. Can be expensive, prefer the
+  /// shared_ptr constructor
   explicit Datum(const RecordBatch& value);
+
+  /// \brief Construct from a Table. Can be expensive, prefer the
+  /// shared_ptr constructor
   explicit Datum(const Table& value);
 
-  // Cast from subtypes of Array or Scalar to Datum
+  /// \brief Cast from concrete types of Array or Scalar to Datum
   template <typename T, bool IsArray = std::is_base_of_v<Array, T>,
             bool IsScalar = std::is_base_of_v<Scalar, T>,
             typename = enable_if_t<IsArray || IsScalar>>
   Datum(std::shared_ptr<T> value)  // NOLINT implicit conversion
       : Datum(std::shared_ptr<typename std::conditional<IsArray, Array, Scalar>::type>(
             std::move(value))) {}
 
-  // Cast from subtypes of Array or Scalar to Datum
+  /// \brief Cast from concrete types of Array or Scalar to Datum
   template <typename T, typename TV = typename std::remove_reference_t<T>,
             bool IsArray = std::is_base_of_v<Array, T>,
             bool IsScalar = std::is_base_of_v<Scalar, T>,
             typename = enable_if_t<IsArray || IsScalar>>
   Datum(T&& value)  // NOLINT implicit conversion
       : Datum(std::make_shared<TV>(std::forward<T>(value))) {}
 
-  // Many Scalars are copyable, let that happen
+  /// \brief Copy from concrete types of Scalar. The scalar type must copyable.

Review Comment:
   ```suggestion
     /// \brief Copy from concrete types of Scalar.
     /// 
     /// The concrete scalar type must be copyable (not all of them are).
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [arrow] pitrou commented on a diff in pull request #35794: GH-35618: [C++][Doc] Improve doc for Datum

Posted by "pitrou (via GitHub)" <gi...@apache.org>.
pitrou commented on code in PR #35794:
URL: https://github.com/apache/arrow/pull/35794#discussion_r1210612036


##########
cpp/src/arrow/datum.h:
##########
@@ -43,14 +43,18 @@ class Table;
 /// \class Datum
 /// \brief Variant type for various Arrow C++ data structures
 struct ARROW_EXPORT Datum {
+  /// \brief The kind of datum stored
   enum Kind { NONE, SCALAR, ARRAY, CHUNKED_ARRAY, RECORD_BATCH, TABLE };
 
+  /// \brief A placeholder type to represent empty datum
   struct Empty {};
 
-  // Datums variants may have a length. This special value indicate that the
-  // current variant does not have a length.
+  /// \brief Datums variants may have a length. This special value indicate that the
+  /// current variant does not have a length.
   static constexpr int64_t kUnknownLength = -1;
 
+  /// \brief Storage of the actual datum. Note: For arrays, it stores ArrayData instead of
+  /// Array for easier data processing

Review Comment:
   Let's keep the brief summary brief and move the rest to the longer description section?
   ```suggestion
     /// \brief Storage of the actual datum.
     ///
     /// Note: For arrays, ArrayData is stored instead of Array for easier processing
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [arrow] pitrou commented on pull request #35794: GH-35618: [C++][Doc] Improve doc for Datum

Posted by "pitrou (via GitHub)" <gi...@apache.org>.
pitrou commented on PR #35794:
URL: https://github.com/apache/arrow/pull/35794#issuecomment-1570878842

   CI failures are unrelated, will merge.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org