From 9fb68b416cbb5acc473d52f00f38a8e768c3c911 Mon Sep 17 00:00:00 2001
From: Matthew Jaffee <jaffee@pilosa.com>
Date: Fri, 27 May 2022 10:57:05 -0500
Subject: [PATCH] add doc comments

---
 api.go             | 4 ++++
 client/batch.go    | 2 ++
 client/client.go   | 1 +
 handler.go         | 2 ++
 roaring/roaring.go | 1 +
 5 files changed, 10 insertions(+)

diff --git a/api.go b/api.go
index a697066d6..d0a5c396d 100644
--- a/api.go
+++ b/api.go
@@ -1603,6 +1603,10 @@ func (api *API) ImportWithTx(ctx context.Context, qcx *Qcx, req *ImportRequest,
 	return errors.Wrap(err, "committing")
 }
 
+// ImportRoaringShard transactionally imports roaring-encoded data
+// across many fields in a single shard. It can both set and clear
+// bits and updates caches/bitDepth as appropriate, although only the
+// bitmap parts happen truly transactionally.
 func (api *API) ImportRoaringShard(ctx context.Context, indexName string, shard uint64, req *ImportRoaringShardRequest) error {
 	index, err := api.Index(ctx, indexName)
 	if err != nil {
diff --git a/client/batch.go b/client/batch.go
index f2f427765..b37895ea0 100644
--- a/client/batch.go
+++ b/client/batch.go
@@ -211,6 +211,8 @@ func OptKeyTranslateBatchSize(v int) BatchOption {
 	}
 }
 
+// OptUseShardTransactionalEndpoint tells the batch to import using
+// the newer shard-transactional endpoint.
 func OptUseShardTransactionalEndpoint(use bool) BatchOption {
 	return func(b *Batch) error {
 		b.useShardTransactionalEndpoint = use
diff --git a/client/client.go b/client/client.go
index 11030ee93..7b94185b0 100644
--- a/client/client.go
+++ b/client/client.go
@@ -647,6 +647,7 @@ func (c *Client) importData(uri *pnet.URI, path string, data []byte) error {
 	return nil
 }
 
+// ImportRoaringShard imports into the shard-transactional endpoint.
 func (c *Client) ImportRoaringShard(index string, shard uint64, request *pilosa.ImportRoaringShardRequest) error {
 	uris, err := c.getURIsForShard(index, shard)
 	if err != nil {
diff --git a/handler.go b/handler.go
index 9145c6140..caac2f815 100644
--- a/handler.go
+++ b/handler.go
@@ -349,6 +349,8 @@ type ImportRoaringRequest struct {
 	UpdateExistence bool
 }
 
+// ImportRoaringShardRequest is the request for the shard
+// transactional endpoint.
 type ImportRoaringShardRequest struct {
 	// Has this request already been forwarded to all replicas? If
 	// Remote=false, then the handling server is responsible for
diff --git a/roaring/roaring.go b/roaring/roaring.go
index 0e7a77d8e..78071f505 100644
--- a/roaring/roaring.go
+++ b/roaring/roaring.go
@@ -177,6 +177,7 @@ type unionContainerIterator struct {
 	cur   FilterKey
 }
 
+// NewUnionContainerIterator unions multiple container iterators to one.
 func NewUnionContainerIterator(iters ...ContainerIterator) ContainerIterator {
 	return &unionContainerIterator{
 		iters: iters,