From 8dec033bd6023202c09055bd602efa99c04218b5 Mon Sep 17 00:00:00 2001
From: Luiz Aoqui <luiz@hashicorp.com>
Date: Tue, 12 Apr 2022 10:27:22 -0400
Subject: [PATCH] add some godocs for the API pagination tokenizer options
 (#12547)

---
 nomad/state/paginator/tokenizer.go | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/nomad/state/paginator/tokenizer.go b/nomad/state/paginator/tokenizer.go
index 527f547a2..7f44d89aa 100644
--- a/nomad/state/paginator/tokenizer.go
+++ b/nomad/state/paginator/tokenizer.go
@@ -31,6 +31,29 @@ type CreateIndexGetter interface {
 }
 
 // StructsTokenizerOptions is the configuration provided to a StructsTokenizer.
+//
+// These are some of the common use cases:
+//   - Structs that can be uniquely identified with only its own ID:
+//
+//       StructsTokenizerOptions {
+//           WithID: true,
+//       }
+//
+//   - Structs that are only unique within their namespace:
+//
+//       StructsTokenizerOptions {
+//           WithID:        true,
+//           WithNamespace: true,
+//       }
+//
+//   - Structs that can be sorted by their create index should also set
+//     `WithCreateIndex` to `true` along with the other options:
+//
+//       StructsTokenizerOptions {
+//           WithID:          true,
+//           WithNamespace:   true,
+//           WithCreateIndex: true,
+//       }
 type StructsTokenizerOptions struct {
 	WithCreateIndex bool
 	WithNamespace   bool