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

["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