doc: add comments to public client methods

internal/docs/code-generation.md

@@ -13,6 +13,8 @@ Before running following commands, ensure that you are logged in to fern:
 ```shell
 make fern-login
 ```
+Note that the code generation automation supports fern version [0.15.10](https://github.com/fern-api/fern/releases/tag/0.15.10).
+If there is an issue with code generation, ensure that the installed fern is in the supported version.
 
 Generate code for `core` scope
 ```shell

xata/branch_client.go

@@ -57,10 +57,14 @@ func (b branchCli) dbBranchName(dbName *string, branchName string) (string, erro
 	return fmt.Sprintf("%s:%s", *dbName, branchName), nil
 }
 
+// List lists all available branches.
+// https://xata.io/docs/api-reference/dbs/db_name#list-branches
 func (b branchCli) List(ctx context.Context, dbName string) (*xatagenworkspace.ListBranchesResponse, error) {
 	return b.generated.GetBranchList(ctx, dbName)
 }
 
+// GetDetails gets branch schema and metadata.
+// https://xata.io/docs/api-reference/db/db_branch_name#get-branch-schema-and-metadata
 func (b branchCli) GetDetails(ctx context.Context, request BranchRequest) (*xatagenworkspace.DbBranch, error) {
 	dbBranchName, err := b.dbBranchName(request.DatabaseName, request.BranchName)
 	if err != nil {
@@ -70,6 +74,8 @@ func (b branchCli) GetDetails(ctx context.Context, request BranchRequest) (*xata
 	return b.generated.GetBranchDetails(ctx, dbBranchName)
 }
 
+// Create creates a database branch.
+// https://xata.io/docs/api-reference/db/db_branch_name#create-database-branch
 func (b branchCli) Create(ctx context.Context, request CreateBranchRequest) (*xatagenworkspace.CreateBranchResponse, error) {
 	dbBranchName, err := b.dbBranchName(request.DatabaseName, request.BranchName)
 	if err != nil {
@@ -94,6 +100,8 @@ func (b branchCli) Create(ctx context.Context, request CreateBranchRequest) (*xa
 	return b.generated.CreateBranch(ctx, dbBranchName, req)
 }
 
+// Delete deletes a database branch.
+// https://xata.io/docs/api-reference/db/db_branch_name#delete-database-branch
 func (b branchCli) Delete(ctx context.Context, request BranchRequest) (*xatagenworkspace.DeleteBranchResponse, error) {
 	dbBranchName, err := b.dbBranchName(request.DatabaseName, request.BranchName)
 	if err != nil {
@@ -103,6 +111,7 @@ func (b branchCli) Delete(ctx context.Context, request BranchRequest) (*xatagenw
 	return b.generated.DeleteBranch(ctx, dbBranchName)
 }
 
+// NewBranchClient constructs a new client to interact with database branches.
 func NewBranchClient(opts ...ClientOption) (BranchClient, error) {
 	cliOpts, dbCfg, err := consolidateClientOptionsForWorkspace(opts...)
 	if err != nil {

xata/client_options.go

@@ -99,6 +99,7 @@ func WithHTTPClient(client httpClient) func(options *ClientOptions) {
 	}
 }
 
+// WithBaseURL enables passing the base URL.
 func WithBaseURL(baseURL string) func(options *ClientOptions) {
 	return func(options *ClientOptions) {
 		options.BaseURL = baseURL

xata/databases_client.go

@@ -51,6 +51,8 @@ type databaseCli struct {
 	Region      string
 }
 
+// Create creates a database.
+// https://xata.io/docs/api-reference/workspaces/workspace_id/dbs/db_name#create-database
 func (d databaseCli) Create(ctx context.Context, request CreateDatabaseRequest) (*xatagencore.CreateDatabaseResponse, error) {
 	var workspaceID string
 	if request.WorkspaceID == nil {
@@ -81,6 +83,8 @@ func (d databaseCli) Create(ctx context.Context, request CreateDatabaseRequest)
 	})
 }
 
+// Delete deletes a database.
+// https://xata.io/docs/api-reference/workspaces/workspace_id/dbs/db_name#delete-database
 func (d databaseCli) Delete(ctx context.Context, request DeleteDatabaseRequest) (*xatagencore.DeleteDatabaseResponse, error) {
 	var workspaceID string
 	if request.WorkspaceID == nil {
@@ -92,22 +96,32 @@ func (d databaseCli) Delete(ctx context.Context, request DeleteDatabaseRequest)
 	return d.generated.DeleteDatabase(ctx, workspaceID, request.DatabaseName)
 }
 
+// GetRegions lists available regions.
+// https://xata.io/docs/api-reference/workspaces/workspace_id/regions#list-available-regions
 func (d databaseCli) GetRegions(ctx context.Context) (*xatagencore.ListRegionsResponse, error) {
 	return d.generated.ListRegions(ctx, d.WorkspaceID)
 }
 
+// GetRegionsWithWorkspaceID lists available regions for a given workspace ID.
+// https://xata.io/docs/api-reference/workspaces/workspace_id/regions#list-available-regions
 func (d databaseCli) GetRegionsWithWorkspaceID(ctx context.Context, workspaceID string) (*xatagencore.ListRegionsResponse, error) {
 	return d.generated.ListRegions(ctx, workspaceID)
 }
 
+// List lists databases.
+// https://xata.io/docs/api-reference/workspaces/workspace_id/dbs#list-databases
 func (d databaseCli) List(ctx context.Context) (*xatagencore.ListDatabasesResponse, error) {
 	return d.generated.GetDatabaseList(ctx, d.WorkspaceID)
 }
 
+// ListWithWorkspaceID lists databases for a given workspace ID.
+// https://xata.io/docs/api-reference/workspaces/workspace_id/dbs#list-databases
 func (d databaseCli) ListWithWorkspaceID(ctx context.Context, workspaceID string) (*xatagencore.ListDatabasesResponse, error) {
 	return d.generated.GetDatabaseList(ctx, workspaceID)
 }
 
+// Rename renames a database.
+// https://xata.io/docs/api-reference/workspaces/workspace_id/dbs/db_name/rename#rename-database
 func (d databaseCli) Rename(ctx context.Context, request RenameDatabaseRequest) (*xatagencore.DatabaseMetadata, error) {
 	wsID := d.WorkspaceID
 	if request.WorkspaceID != nil && *request.WorkspaceID != "" {
@@ -122,6 +136,7 @@ func (d databaseCli) Rename(ctx context.Context, request RenameDatabaseRequest)
 	)
 }
 
+// NewDatabasesClient constructs a client for interacting databases.
 func NewDatabasesClient(opts ...ClientOption) (DatabasesClient, error) {
 	cliOpts, err := consolidateClientOptionsForCore(opts...)
 	if err != nil {

xata/files_cilent.go

@@ -50,6 +50,8 @@ type DeleteFileRequest struct {
 	ColumnName string
 }
 
+// Delete removes the content from a file column.
+// https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name/data/record_id/column/column_name/file#remove-the-content-from-a-file-column
 func (f filesClient) Delete(ctx context.Context, request DeleteFileRequest) (*xatagenworkspace.FileResponse, error) {
 	dbBranchName, err := f.dbBranchName(request.BranchRequestOptional)
 	if err != nil {
@@ -68,6 +70,8 @@ type PutFileRequest struct {
 	Data        []byte
 }
 
+// Put uploads content to a file column.
+// https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name/data/record_id/column/column_name/file#upload-content-to-a-file-column
 func (f filesClient) Put(ctx context.Context, request PutFileRequest) (*xatagenworkspace.FileResponse, error) {
 	dbBranchName, err := f.dbBranchName(request.BranchRequestOptional)
 	if err != nil {
@@ -91,6 +95,8 @@ type GetFileRequest struct {
 	ColumnName string
 }
 
+// Get downloads content from a file column.
+// https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name/data/record_id/column/column_name/file#download-content-from-a-file-column
 func (f filesClient) Get(ctx context.Context, request GetFileRequest) (*xatagenworkspace.GetFileResponse, error) {
 	dbBranchName, err := f.dbBranchName(request.BranchRequestOptional)
 	if err != nil {
@@ -108,6 +114,8 @@ type GetFileItemRequest struct {
 	FileID     string
 }
 
+// GetItem downloads content from a file item in a file array column.
+// https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name/data/record_id/column/column_name/file/file_id#download-content-from-a-file-item-in-a-file-array-column
 func (f filesClient) GetItem(ctx context.Context, request GetFileItemRequest) (*xatagenworkspace.GetFileResponse, error) {
 	dbBranchName, err := f.dbBranchName(request.BranchRequestOptional)
 	if err != nil {
@@ -127,6 +135,8 @@ type PutFileItemRequest struct {
 	Data        []byte
 }
 
+// PutItem uploads or updates the content of a file item in a file array column.
+// https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name/data/record_id/column/column_name/file/file_id#upload-or-update-the-content-of-a-file-item-in-a-file-array-column
 func (f filesClient) PutItem(ctx context.Context, request PutFileItemRequest) (*xatagenworkspace.FileResponse, error) {
 	dbBranchName, err := f.dbBranchName(request.BranchRequestOptional)
 	if err != nil {
@@ -151,6 +161,8 @@ type DeleteFileItemRequest struct {
 	FileID     string
 }
 
+// DeleteItem deletes an item from a file array.
+// https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name/data/record_id/column/column_name/file/file_id#delete-an-item-from-a-file-array
 func (f filesClient) DeleteItem(ctx context.Context, request DeleteFileItemRequest) (*xatagenworkspace.FileResponse, error) {
 	dbBranchName, err := f.dbBranchName(request.BranchRequestOptional)
 	if err != nil {
@@ -160,6 +172,7 @@ func (f filesClient) DeleteItem(ctx context.Context, request DeleteFileItemReque
 	return f.generated.DeleteFileItem(ctx, dbBranchName, request.TableName, request.RecordID, request.ColumnName, request.FileID)
 }
 
+// NewFilesClient constructs a client for interacting files.
 func NewFilesClient(opts ...ClientOption) (FilesClient, error) {
 	cliOpts, dbCfg, err := consolidateClientOptionsForWorkspace(opts...)
 	if err != nil {

xata/records_client.go

@@ -147,6 +147,8 @@ type recordsClient struct {
 	branchName string
 }
 
+// Insert inserts a record.
+// https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name/data#insert-record
 func (r recordsClient) Insert(ctx context.Context, request InsertRecordRequest) (*Record, error) {
 	recGen := &xatagenworkspace.InsertRecordRequest{
 		Columns: constructColumns(request.Columns),
@@ -175,6 +177,8 @@ func (r recordsClient) Insert(ctx context.Context, request InsertRecordRequest)
 	return respRec, nil
 }
 
+// BulkInsert bulk inserts records.
+// https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name/bulk#bulk-insert-records
 func (r recordsClient) BulkInsert(ctx context.Context, request BulkInsertRecordRequest) ([]*Record, error) {
 	recGen := &xatagenworkspace.BulkInsertTableRecordsRequest{
 		Columns: constructColumns(request.Columns),
@@ -201,6 +205,8 @@ func (r recordsClient) BulkInsert(ctx context.Context, request BulkInsertRecordR
 	return constructBulkRecords(*records)
 }
 
+// InsertWithID inserts records with ID.
+// https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name/data/record_id#insert-record-with-id
 func (r recordsClient) InsertWithID(ctx context.Context, request InsertRecordWithIDRequest) (*Record, error) {
 	recGen := &xatagenworkspace.InsertRecordWithIdRequest{
 		CreateOnly: request.CreateOnly,
@@ -231,6 +237,8 @@ func (r recordsClient) InsertWithID(ctx context.Context, request InsertRecordWit
 	return respRec, nil
 }
 
+// Update updates a record.
+// https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name/data/record_id#update-record-with-id
 func (r recordsClient) Update(ctx context.Context, request UpdateRecordRequest) (*Record, error) {
 	recGen := &xatagenworkspace.UpdateRecordWithIdRequest{
 		IfVersion: request.IfVersion,
@@ -260,6 +268,8 @@ func (r recordsClient) Update(ctx context.Context, request UpdateRecordRequest)
 	return respRec, nil
 }
 
+// Upsert inserts or updates a record.
+// https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name/data/record_id#upsert-record-with-id
 func (r recordsClient) Upsert(ctx context.Context, request UpsertRecordRequest) (*Record, error) {
 	recGen := &xatagenworkspace.UpdateRecordWithIdRequest{
 		IfVersion: request.IfVersion,
@@ -289,6 +299,8 @@ func (r recordsClient) Upsert(ctx context.Context, request UpsertRecordRequest)
 	return respRec, nil
 }
 
+// Get gets a record by its ID.
+// https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name/data/record_id#upsert-record-with-id
 func (r recordsClient) Get(ctx context.Context, request GetRecordRequest) (*Record, error) {
 	getRecReq := &xatagenworkspace.GetRecordRequest{
 		Columns: constructColumns(request.Columns),
@@ -352,6 +364,8 @@ func NewDeleteTransaction(value TransactionDeleteOp) TransactionOperation {
 	})
 }
 
+// Transaction executes a transaction on a branch.
+// https://xata.io/docs/api-reference/db/db_branch_name/transaction#execute-a-transaction-on-a-branch
 func (r recordsClient) Transaction(ctx context.Context, request TransactionRequest) (*xatagenworkspace.TransactionSuccess, error) {
 	dbBranchName, err := r.dbBranchName(request.RecordRequest)
 	if err != nil {
@@ -368,6 +382,8 @@ func (r recordsClient) Transaction(ctx context.Context, request TransactionReque
 	})
 }
 
+// Delete deletes a record from a table.
+// https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name/data/record_id#delete-record-from-table
 func (r recordsClient) Delete(ctx context.Context, request DeleteRecordRequest) error {
 	dbBranchName, err := r.dbBranchName(request.RecordRequest)
 	if err != nil {
@@ -451,6 +467,7 @@ func constructRecord(in map[string]interface{}) (*Record, error) {
 	return &record, nil
 }
 
+// NewRecordsClient constructs a clint for interacting with records.
 func NewRecordsClient(opts ...ClientOption) (RecordsClient, error) {
 	cliOpts, dbCfg, err := consolidateClientOptionsForWorkspace(opts...)
 	if err != nil {

xata/search_filter_client.go

@@ -64,6 +64,8 @@ type QueryTableRequest struct {
 	Payload   QueryTableRequestPayload
 }
 
+// Query queries a table.
+// https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name/query#query-table
 func (s searchAndFilterCli) Query(ctx context.Context, request QueryTableRequest) (*xatagenworkspace.QueryTableResponse, error) {
 	dbBranchName, err := s.dbBranchName(request.BranchRequestOptional)
 	if err != nil {
@@ -93,6 +95,8 @@ type SearchBranchRequest struct {
 	Payload SearchBranchRequestPayload
 }
 
+// SearchBranch runs a free text search operation across the database branch.
+// https://xata.io/docs/api-reference/db/db_branch_name/search#free-text-search
 func (s searchAndFilterCli) SearchBranch(ctx context.Context, request SearchBranchRequest) (*xatagenworkspace.SearchBranchResponse, error) {
 	dbBranchName, err := s.dbBranchName(request.BranchRequestOptional)
 	if err != nil {
@@ -133,6 +137,8 @@ type SearchTableRequest struct {
 	Payload   SearchTableRequestPayload
 }
 
+// SearchTable runs a free text search in a table.
+// https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name/search#free-text-search-in-a-table
 func (s searchAndFilterCli) SearchTable(ctx context.Context, request SearchTableRequest) (*xatagenworkspace.SearchTableResponse, error) {
 	dbBranchName, err := s.dbBranchName(request.BranchRequestOptional)
 	if err != nil {
@@ -179,6 +185,8 @@ type VectorSearchTableRequest struct {
 	Payload   VectorSearchTableRequestPayload
 }
 
+// VectorSearch performs vector-based similarity searches in a table.
+// https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name/vectorSearch#vector-similarity-search-in-a-table
 func (s searchAndFilterCli) VectorSearch(ctx context.Context, request VectorSearchTableRequest) (*xatagenworkspace.VectorSearchTableResponse, error) {
 	dbBranchName, err := s.dbBranchName(request.BranchRequestOptional)
 	if err != nil {
@@ -223,6 +231,8 @@ type AskTableRequest struct {
 	Payload   AskTableRequestPayload
 }
 
+// Ask asks your table a question.
+// https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name/ask#ask-your-table-a-question
 func (s searchAndFilterCli) Ask(ctx context.Context, request AskTableRequest) (*xatagenworkspace.AskTableResponse, error) {
 	dbBranchName, err := s.dbBranchName(request.BranchRequestOptional)
 	if err != nil {
@@ -269,6 +279,8 @@ type AskFollowUpRequest struct {
 	Question  string
 }
 
+// AskFollowUp enables asking a follow-up question.
+// https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name/ask/session_id#continue-a-conversation-with-your-data
 func (s searchAndFilterCli) AskFollowUp(ctx context.Context, request AskFollowUpRequest) (*xatagenworkspace.AskTableSessionResponse, error) {
 	dbBranchName, err := s.dbBranchName(request.BranchRequestOptional)
 	if err != nil {
@@ -301,6 +313,8 @@ type SummarizeTableRequest struct {
 	Payload   SummarizeTableRequestPayload
 }
 
+// Summarize summarizes a table for the given parameters.
+// https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name/summarize#summarize-table
 func (s searchAndFilterCli) Summarize(ctx context.Context, request SummarizeTableRequest) (*xatagenworkspace.SummarizeTableResponse, error) {
 	dbBranchName, err := s.dbBranchName(request.BranchRequestOptional)
 	if err != nil {
@@ -345,6 +359,8 @@ type AggregateTableRequest struct {
 	Payload   AggregateTableRequestPayload
 }
 
+// Aggregate runs aggregations (analytics) on the data from one table.
+// https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name/aggregate#run-aggregations-over-a-table
 func (s searchAndFilterCli) Aggregate(ctx context.Context, request AggregateTableRequest) (*xatagenworkspace.AggregateTableResponse, error) {
 	dbBranchName, err := s.dbBranchName(request.BranchRequestOptional)
 	if err != nil {
@@ -365,6 +381,7 @@ func (s searchAndFilterCli) Aggregate(ctx context.Context, request AggregateTabl
 	})
 }
 
+// NewSearchAndFilterClient constructs a new search and filter client.
 func NewSearchAndFilterClient(opts ...ClientOption) (SearchAndFilterClient, error) {
 	cliOpts, dbCfg, err := consolidateClientOptionsForWorkspace(opts...)
 	if err != nil {

xata/table_client.go

@@ -94,6 +94,8 @@ type AddColumnRequest struct {
 	Column *Column
 }
 
+// AddColumn creates a new column.
+// https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name/columns#create-new-column
 func (t tableClient) AddColumn(ctx context.Context, request AddColumnRequest) (*xatagenworkspace.AddTableColumnResponse, error) {
 	return t.generated.AddTableColumn(ctx, t.dbBranchName(request.TableRequest), request.TableName, copyColumn(*request.Column))
 }
@@ -118,18 +120,25 @@ type DeleteColumnRequest struct {
 	ColumnName string
 }
 
+// DeleteColumn deletes a column.
+// https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name/columns/column_name#delete-column
 func (t tableClient) DeleteColumn(ctx context.Context, request DeleteColumnRequest) (*xatagenworkspace.DeleteColumnResponse, error) {
 	return t.generated.DeleteColumn(ctx, t.dbBranchName(request.TableRequest), request.TableName, request.ColumnName)
 }
 
+// GetSchema gets the schema of a table.
+// https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name/schema#get-table-schema
 func (t tableClient) GetSchema(ctx context.Context, request TableRequest) (*xatagenworkspace.GetTableSchemaResponse, error) {
 	return t.generated.GetTableSchema(ctx, t.dbBranchName(request), request.TableName)
 }
 
+// GetColumns retrieves the list of table columns and their definition.
+// https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name/columns#list-table-columns
 func (t tableClient) GetColumns(ctx context.Context, request TableRequest) (*xatagenworkspace.GetTableColumnsResponse, error) {
 	return t.generated.GetTableColumns(ctx, t.dbBranchName(request), request.TableName)
 }
 
+// NewTableClient constructs a client for interacting tables.
 func NewTableClient(opts ...ClientOption) (TableClient, error) {
 	cliOpts, dbCfg, err := consolidateClientOptionsForWorkspace(opts...)
 	if err != nil {

xata/users_client.go

@@ -17,10 +17,13 @@ type usersCli struct {
 	generated xatagencore.UsersClient
 }
 
+// Get returns details of the user making the request.
+// https://xata.io/docs/api-reference/user#get-user-details
 func (u usersCli) Get(ctx context.Context) (*xatagencore.UserWithId, error) {
 	return u.generated.GetUser(ctx)
 }
 
+// NewUsersClient constructs a client for interacting users.
 func NewUsersClient(opts ...ClientOption) (UsersClient, error) {
 	cliOpts, err := consolidateClientOptionsForCore(opts...)
 	if err != nil {