[CDX-241] Docs: Update docs for filterName and filterValue

[evanyan13]

Changes

• Update docs in CIOBrowseQuery struct
• Update docs in CIOBrowseQueryBuilder class

[Copilot]

Pull request overview

This PR updates documentation for filterName and filterValue parameters across the codebase to provide more accurate and detailed guidance. The changes clarify that filterName should typically be "group_id" for browsing item groups, and update example values from generic placeholders to more realistic ones.

• Replaces vague documentation with specific guidance on valid filterName values ("group_id", "collection_id", or facet names)
• Updates example code snippets to use "sales" as a more realistic filterValue instead of "Pantry" or "russet"
• Adds usage examples to help developers understand proper parameter usage

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
AutocompleteClient/FW/Logic/Worker/ConstructorIO.swift	Updated documentation for browse tracking method parameters and example code to use "sales" instead of "Pantry"
AutocompleteClient/FW/Logic/Request/CIOBrowseQuery.swift	Enhanced parameter documentation with detailed descriptions of valid values and added usage example with "sales" filterValue
AutocompleteClient/FW/Logic/Request/Builder/CIOBrowseQueryBuilder.swift	Updated initializer documentation and example code, replacing "russet" with "sales" for consistency

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[constructor-claude-bedrock]

Code Review Summary

This PR updates the documentation for filterName and filterValue parameters in the Browse Query API. The changes improve clarity by providing specific examples and clearer explanations of the possible values these parameters can accept. Overall, this is a valuable documentation improvement that will help developers understand how to use the Browse API correctly.

Detailed Feedback

Positive Changes

• [General] Excellent improvement in documentation clarity. The new descriptions clearly explain what filterName and filterValue represent, with concrete examples of possible values ("group_id", "collection_id", facet names).

• [General] The addition of usage examples directly in the initializer documentation (CIOBrowseQueryBuilder.swift:90-94 and CIOBrowseQuery.swift:105-106) is very helpful for developers.

• [General] Updating example values from placeholder values like "potato"/"russet" and "Pantry" to more realistic and consistent examples like "group_id"/"sales" makes the documentation more professional and clearer.

Issues Found

• [File: AutocompleteClient/FW/Logic/Request/Builder/CIOBrowseQueryBuilder.swift Lines: L87-88] Minor punctuation inconsistency: The parameter descriptions end with commas inside the quotes ("group_id," and "collection_id,") which looks slightly awkward. Consider removing the trailing commas from within the quoted strings for cleaner formatting:

  - filterName: The attribute name that defines what you are browsing by. Possible values are: "group_id", "collection_id", or "[facet_name]" where the facet name corresponds with a facet defined in the catalog. Use "group_id" by default for browsing item groups.

• [File: AutocompleteClient/FW/Logic/Request/CIOBrowseQuery.swift Lines: L91-92] Same punctuation inconsistency as above. The trailing commas inside the quoted strings should be removed for consistency and cleaner formatting.

• [File: AutocompleteClient/FW/Logic/Request/CIOBrowseQuery.swift Line: L88] Minor typo in the existing documentation (not introduced by this PR, but worth fixing while updating docs): "hiddenFacets" parameter description has a typo: "The list of hidden facest to return" should be "The list of hidden facets to return" (line 99).

• [File: AutocompleteClient/FW/Logic/Worker/ConstructorIO.swift Lines: L456] Inconsistency in documentation examples: The usage example for trackBrowseResultsLoaded still uses "Category"/"Snacks" as filterName/filterValue, while the parameter documentation now uses "group_id"/"sales". For consistency across the codebase, consider updating this example to also use "group_id"/"sales" or at least ensure it matches the pattern described in the parameter documentation.

Conclusion

This is a solid documentation improvement PR that significantly enhances the clarity of the Browse API parameters. The issues identified are minor and primarily related to punctuation consistency and a pre-existing typo. I recommend addressing the punctuation inconsistencies for polish, but they don't block approval. Great work on making the API more accessible to developers! ✅

Recommendation: Approve with minor suggestions for improvement.

[esezen]

Looking good. Thanks for working on this. Can we update the code example?

[constructor-claude-bedrock]

Code Review Summary

This PR updates the documentation for filterName and filterValue parameters across the codebase to provide clearer guidance on their usage. The changes enhance the documentation by explaining what these parameters represent and providing concrete examples. Overall, this is a documentation-only PR that significantly improves developer experience by clarifying the purpose and valid values for browse functionality.

Detailed Feedback

Positive Aspects

✅ Comprehensive Documentation Updates: The PR systematically updates documentation across multiple files (CIOBrowseQuery, CIOBrowseQueryBuilder, ConstructorIO.swift, and README.md), ensuring consistency.

✅ Clear Value Guidance: The new documentation explicitly lists possible values for filterName ("group_id", "collection_id", "[facet_name]") which is very helpful for developers.

✅ Improved Examples: Replacing placeholder values like "potato"/"russet" and "Pantry" with more meaningful examples like "group_id"/"sales" makes the examples more realistic and easier to understand.

✅ Context-Rich Documentation: Adding explanatory text like "Use 'group_id' by default for browsing item groups" provides valuable context about common use cases.

Specific Comments

[File: AutocompleteClient/FW/Logic/Request/Builder/CIOBrowseQueryBuilder.swift Lines: L87-94]
The expanded documentation for filterName is excellent. It clearly explains the parameter's purpose and lists valid values with proper formatting. Consider adding a brief note about when to use each option (e.g., "Use 'collection_id' when browsing by collections, 'group_id' when browsing by item groups").

[File: AutocompleteClient/FW/Logic/Request/CIOBrowseQuery.swift Lines: L91-98]
The documentation here matches the builder class well, maintaining consistency. Good work!

[File: AutocompleteClient/FW/Logic/Worker/ConstructorIO.swift Lines: L444-445]
The updated tracking function documentation now uses "group_id" and "sales" as examples, which aligns perfectly with the browse query documentation. This consistency across the codebase is excellent.

[File: README.md Line: L159]
Great update to use a realistic example ("group_id"/"sales") instead of the playful "potato"/"russet". This makes the README more professional and educational.

[General: Documentation Formatting]
The markdown formatting in the docstrings is clean and well-structured. The use of bullet points, sub-bullets, and code examples makes the documentation easy to scan and understand.

Minor Suggestions

1. [File: AutocompleteClient/FW/Logic/Request/CIOBrowseQuery.swift Line: L98]: The example values "sales", "mens-jeans" are good, but consider adding one more example that shows using a facet name to make it crystal clear. For instance: Eg. "sales" (for group_id), "mens-jeans" (for collection_id), "blue" (for a Color facet)

2. [File: AutocompleteClient/FW/Logic/Request/Builder/CIOBrowseQueryBuilder.swift Line: L92]: The notation "[facet_name]" with brackets might be slightly confusing. Consider clarifying that this is a placeholder notation, e.g., "[facet_name] (replace with actual facet name from your catalog, e.g., 'Color', 'Size', 'Brand')"

3. [General]: While the examples now consistently use "group_id" and "sales", it might be beneficial to have one example somewhere in the codebase that demonstrates using a different filterName value (like "collection_id") to showcase the flexibility.

Conclusion

Verdict: ✅ APPROVED

This is an excellent documentation improvement PR. The changes are clear, consistent, and significantly enhance the developer experience by providing concrete guidance on how to use the browse functionality. The replacement of placeholder examples with realistic values makes the SDK more approachable for new developers.

The documentation now clearly communicates:

• What filterName and filterValue represent
• Valid values for filterName
• Concrete examples of proper usage
• Consistency across all usage points in the codebase

No blocking issues found. The minor suggestions above are optional enhancements that could further improve clarity, but the PR is ready to merge as-is.

Great work on improving the developer documentation! 🎉