add some godocs for the API pagination tokenizer options (#12547)

hashicorp · Apr 12, 2022 · 8dec033 · 8dec033
1 parent 247e20e
commit 8dec033
Showing 1 changed file with 23 additions and 0 deletions.
diff --git 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