[GitHub] [arrow-adbc] lidavidm commented on a diff in pull request #428: docs(format): clarify some parts of header file

["lidavidm (via GitHub)" <gi...@apache.org>]

lidavidm commented on code in PR #428:
URL: https://github.com/apache/arrow-adbc/pull/428#discussion_r1099047614


##########
adbc.h:
##########
@@ -675,6 +675,13 @@ struct ADBC_EXPORT AdbcDriver {
 /// @{
 
 /// \brief Allocate a new (but uninitialized) database.
+///
+/// Callers pass in AdbcDatabase with private_data set to NULL and the
+/// private_driver possibly set.

Review Comment:
   ```suggestion
   /// Callers pass in a zero-initialized AdbcDatabase.
   ```



##########
adbc.h:
##########
@@ -709,6 +716,13 @@ AdbcStatusCode AdbcDatabaseRelease(struct AdbcDatabase* database,
 /// @{
 
 /// \brief Allocate a new (but uninitialized) connection.
+///
+/// Callers pass in AdbcConnection with private_data set to NULL and the
+/// private_driver possibly set.

Review Comment:
   ```suggestion
   /// Callers pass in a zero-initialized AdbcConnection.
   ```



##########
adbc.h:
##########
@@ -1183,7 +1204,11 @@ AdbcStatusCode AdbcStatementExecutePartitions(struct AdbcStatement* statement,
 ///   driver.
 ///
 /// Although drivers may choose any name for this function, the
-/// recommended name is "AdbcDriverInit".
+/// recommended name is "AdbcDriverInit". If you use the recommended
+/// name, then driver managers will be able to automatically find
+/// the entrypoint function. Drivers may also expose the same function
+/// under a unique symbol so that multiple drivers can be statically
+/// linked into a single binary without any conflicts.

Review Comment:
   Though, the definitions of Adbc* will still conflict; the only way to use them would be via the driver manager (and whatever linker trickery is necessary to prefer the driver manager's implementation of all such symbols)



##########
adbc.h:
##########
@@ -1013,6 +1027,13 @@ AdbcStatusCode AdbcConnectionRollback(struct AdbcConnection* connection,
 ///
 /// Set options on the statement, then call AdbcStatementExecuteQuery
 /// or AdbcStatementPrepare.
+///
+/// Callers pass in AdbcStatement with private_data set to NULL and the
+/// private_driver possibly set.

Review Comment:
   ```suggestion
   /// Callers pass in a zero-initialized AdbcStatement.
   ```



##########
adbc.h:
##########
@@ -1183,7 +1204,11 @@ AdbcStatusCode AdbcStatementExecutePartitions(struct AdbcStatement* statement,
 ///   driver.
 ///
 /// Although drivers may choose any name for this function, the
-/// recommended name is "AdbcDriverInit".
+/// recommended name is "AdbcDriverInit". If you use the recommended
+/// name, then driver managers will be able to automatically find
+/// the entrypoint function. Drivers may also expose the same function

Review Comment:
   ```suggestion
   /// the entrypoint function. Drivers should also expose the same function
   ```



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