pitrou commented on code in PR #13527:
URL: https://github.com/apache/arrow/pull/13527#discussion_r918982942
##########
cpp/src/arrow/engine/substrait/serde.h:
##########
@@ -36,193 +36,193 @@ namespace arrow {
namespace engine {
/// Factory function type for generating the node that consumes the batches
produced by
-/// each toplevel Substrait relation when deserializing a Substrait Plan.
+/// each top-level Substrait relation when deserializing a Substrait Plan.
using ConsumerFactory =
std::function<std::shared_ptr<compute::SinkNodeConsumer>()>;
-/// \brief Deserializes a Substrait Plan message to a list of ExecNode
declarations
+/// \brief Deserializes a Substrait Plan message to a list of ExecNode
declarations.
///
/// The output of each top-level Substrait relation will be sent to a caller
supplied
-/// consumer function provided by consumer_factory
+/// consumer function provided by consumer_factory.
///
/// \param[in] buf a buffer containing the protobuf serialization of a
Substrait Plan
-/// message
+/// message.
/// \param[in] consumer_factory factory function for generating the node that
consumes
-/// the batches produced by each toplevel Substrait relation
+/// the batches produced by each top-level Substrait relation.
/// \param[in] registry an extension-id-registry to use, or null for the
default one.
/// \param[out] ext_set_out if non-null, the extension mapping used by the
Substrait
/// Plan is returned here.
-/// \return a vector of ExecNode declarations, one for each toplevel relation
in the
-/// Substrait Plan
+/// \return a vector of ExecNode declarations, one for each top-level relation
in the
+/// Substrait Plan.
ARROW_ENGINE_EXPORT Result<std::vector<compute::Declaration>> DeserializePlans(
const Buffer& buf, const ConsumerFactory& consumer_factory,
const ExtensionIdRegistry* registry = NULLPTR, ExtensionSet* ext_set_out =
NULLPTR);
-/// \brief Deserializes a single-relation Substrait Plan message to an
execution plan
+/// \brief Deserializes a single-relation Substrait Plan message to an
execution plan.
///
-/// The output of each top-level Substrait relation will be sent to a caller
supplied
-/// consumer function provided by consumer_factory
+/// The output of each top-level Substrait relation will be sent to the given
consumer.
///
/// \param[in] buf a buffer containing the protobuf serialization of a
Substrait Plan
-/// message
-/// \param[in] consumer node that consumes the batches produced by each
toplevel Substrait
-/// relation
+/// message.
+/// \param[in] consumer node that consumes the batches produced by the
top-level
+/// Substrait relation.
/// \param[in] registry an extension-id-registry to use, or null for the
default one.
/// \param[out] ext_set_out if non-null, the extension mapping used by the
Substrait
/// Plan is returned here.
-/// \return an ExecNode corresponding to the single toplevel relation in the
Substrait
-/// Plan
+/// \return an ExecNode corresponding to the single top-level relation in the
Substrait
+/// Plan.
Result<compute::ExecPlan> DeserializePlan(
const Buffer& buf, const std::shared_ptr<compute::SinkNodeConsumer>&
consumer,
const ExtensionIdRegistry* registry = NULLPTR, ExtensionSet* ext_set_out =
NULLPTR);
/// Factory function type for generating the write options of a node consuming
the batches
-/// produced by each toplevel Substrait relation when deserializing a
Substrait Plan.
+/// produced by each top-level Substrait relation when deserializing a
Substrait Plan.
using WriteOptionsFactory =
std::function<std::shared_ptr<dataset::WriteNodeOptions>()>;
-/// \brief Deserializes a Substrait Plan message to a list of ExecNode
declarations
+/// \brief Deserializes a Substrait Plan message to a list of ExecNode
declarations.
///
/// The output of each top-level Substrait relation will be written to a
filesystem.
/// `write_options_factory` can be used to control write behavior.
///
/// \param[in] buf a buffer containing the protobuf serialization of a
Substrait Plan
-/// message
+/// message.
/// \param[in] write_options_factory factory function for generating the write
options of
-/// a node consuming the batches produced by each toplevel Substrait relation
+/// a node consuming the batches produced by each top-level Substrait relation.
/// \param[in] registry an extension-id-registry to use, or null for the
default one.
/// \param[out] ext_set_out if non-null, the extension mapping used by the
Substrait
/// Plan is returned here.
-/// \return a vector of ExecNode declarations, one for each toplevel relation
in the
-/// Substrait Plan
+/// \return a vector of ExecNode declarations, one for each top-level relation
in the
+/// Substrait Plan.
ARROW_ENGINE_EXPORT Result<std::vector<compute::Declaration>> DeserializePlans(
const Buffer& buf, const WriteOptionsFactory& write_options_factory,
const ExtensionIdRegistry* registry = NULLPTR, ExtensionSet* ext_set_out =
NULLPTR);
-/// \brief Deserializes a single-relation Substrait Plan message to an
execution plan
+/// \brief Deserializes a single-relation Substrait Plan message to an
execution plan.
///
/// The output of the single Substrait relation will be written to a
filesystem.
/// `write_options_factory` can be used to control write behavior.
///
/// \param[in] buf a buffer containing the protobuf serialization of a
Substrait Plan
-/// message
-/// \param[in] write_options write options of a node consuming the batches
produced by
-/// each toplevel Substrait relation
+/// message.
+/// \param[in] write_options write options for the node that will consume the
batches
+/// produced by the top-level Substrait relation.
/// \param[in] registry an extension-id-registry to use, or null for the
default one.
/// \param[out] ext_set_out if non-null, the extension mapping used by the
Substrait
/// Plan is returned here.
-/// \return a vector of ExecNode declarations, one for each toplevel relation
in the
-/// Substrait Plan
+/// \return a vector of ExecNode declarations, one for each top-level relation
in the
+/// Substrait Plan.
ARROW_ENGINE_EXPORT Result<compute::ExecPlan> DeserializePlan(
const Buffer& buf, const std::shared_ptr<dataset::WriteNodeOptions>&
write_options,
const ExtensionIdRegistry* registry = NULLPTR, ExtensionSet* ext_set_out =
NULLPTR);
-/// \brief Deserializes a Substrait Type message to the corresponding Arrow
type
+/// \brief Deserializes a Substrait Type message to the corresponding Arrow
type.
///
/// \param[in] buf a buffer containing the protobuf serialization of a
Substrait Type
-/// message
+/// message.
/// \param[in] ext_set the extension mapping to use, normally provided by the
-/// surrounding Plan message
-/// \return the corresponding Arrow data type
+/// surrounding Plan message.
+/// \return the corresponding Arrow data type.
ARROW_ENGINE_EXPORT
Result<std::shared_ptr<DataType>> DeserializeType(const Buffer& buf,
const ExtensionSet& ext_set);
-/// \brief Serializes an Arrow type to a Substrait Type message
+/// \brief Serializes an Arrow type to a Substrait Type message.
///
-/// \param[in] type the Arrow data type to serialize
+/// \param[in] type the Arrow data type to serialize.
/// \param[in,out] ext_set the extension mapping to use; may be updated to add
a
-/// mapping for the given type
+/// mapping for the given type.
/// \return a buffer containing the protobuf serialization of the
corresponding Substrait
-/// Type message
+/// Type message.
ARROW_ENGINE_EXPORT
Result<std::shared_ptr<Buffer>> SerializeType(const DataType& type,
ExtensionSet* ext_set);
-/// \brief Deserializes a Substrait NamedStruct message to an Arrow schema
+/// \brief Deserializes a Substrait NamedStruct message to an Arrow schema.
///
/// \param[in] buf a buffer containing the protobuf serialization of a
Substrait
-/// NamedStruct message
+/// NamedStruct message.
/// \param[in] ext_set the extension mapping to use, normally provided by the
-/// surrounding Plan message
-/// \return the corresponding Arrow schema
+/// surrounding Plan message.
+/// \return the corresponding Arrow schema.
ARROW_ENGINE_EXPORT
Result<std::shared_ptr<Schema>> DeserializeSchema(const Buffer& buf,
const ExtensionSet& ext_set);
-/// \brief Serializes an Arrow schema to a Substrait NamedStruct message
+/// \brief Serializes an Arrow schema to a Substrait NamedStruct message.
///
-/// \param[in] schema the Arrow schema to serialize
+/// \param[in] schema the Arrow schema to serialize.
/// \param[in,out] ext_set the extension mapping to use; may be updated to add
-/// mappings for the types used in the schema
+/// mappings for the types used in the schema.
/// \return a buffer containing the protobuf serialization of the
corresponding Substrait
-/// NamedStruct message
+/// NamedStruct message.
ARROW_ENGINE_EXPORT
Result<std::shared_ptr<Buffer>> SerializeSchema(const Schema& schema,
ExtensionSet* ext_set);
-/// \brief Deserializes a Substrait Expression message to a compute expression
+/// \brief Deserializes a Substrait Expression message to a compute expression.
///
/// \param[in] buf a buffer containing the protobuf serialization of a
Substrait
-/// Expression message
+/// Expression message.
/// \param[in] ext_set the extension mapping to use, normally provided by the
-/// surrounding Plan message
-/// \return the corresponding Arrow compute expression
+/// surrounding Plan message.
+/// \return the corresponding Arrow compute expression.
ARROW_ENGINE_EXPORT
Result<compute::Expression> DeserializeExpression(const Buffer& buf,
const ExtensionSet& ext_set);
-/// \brief Serializes an Arrow compute expression to a Substrait Expression
message
+/// \brief Serializes an Arrow compute expression to a Substrait Expression
message.
///
-/// \param[in] expr the Arrow compute expression to serialize
+/// \param[in] expr the Arrow compute expression to serialize.
/// \param[in,out] ext_set the extension mapping to use; may be updated to add
-/// mappings for the types used in the expression
+/// mappings for the types used in the expression.
/// \return a buffer containing the protobuf serialization of the
corresponding Substrait
-/// Expression message
+/// Expression message.
ARROW_ENGINE_EXPORT
Result<std::shared_ptr<Buffer>> SerializeExpression(const compute::Expression&
expr,
ExtensionSet* ext_set);
-/// \brief Deserializes a Substrait Rel (relation) message to an ExecNode
declaration
+/// \brief Deserializes a Substrait Rel (relation) message to an ExecNode
declaration.
///
/// \param[in] buf a buffer containing the protobuf serialization of a
Substrait
-/// Rel message
+/// Rel message.
/// \param[in] ext_set the extension mapping to use, normally provided by the
-/// surrounding Plan message
-/// \return the corresponding ExecNode declaration
+/// surrounding Plan message.
+/// \return the corresponding ExecNode declaration.
ARROW_ENGINE_EXPORT Result<compute::Declaration> DeserializeRelation(
const Buffer& buf, const ExtensionSet& ext_set);
namespace internal {
/// \brief Checks whether two protobuf serializations of a particular
Substrait message
-/// type are equivalent
+/// type are equivalent.
///
/// Note that a binary comparison of the two buffers is insufficient. One
reason for this
/// is that the fields of a message can be specified in any order in the
serialization.
///
-/// \param[in] message_name the name of the Substrait message type to check
-/// \param[in] l_buf buffer containing the first protobuf serialization to
compare
-/// \param[in] r_buf buffer containing the second protobuf serialization to
compare
-/// \return success if equivalent, failure if not
+/// \param[in] message_name the name of the Substrait message type to check.
+/// \param[in] l_buf buffer containing the first protobuf serialization to
compare.
+/// \param[in] r_buf buffer containing the second protobuf serialization to
compare.
+/// \return success if equivalent, failure if not.
ARROW_ENGINE_EXPORT
Status CheckMessagesEquivalent(util::string_view message_name, const Buffer&
l_buf,
const Buffer& r_buf);
/// \brief Utility function to convert a JSON serialization of a Substrait
message to
Review Comment:
Or if we want to keep it concise
```suggestion
/// \brief Convert a JSON serialization of a Substrait message to
```
--
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: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
