docs: numpy-style docstrings on Favorites endpoint (15 methods) - #1855
Open
jacalata wants to merge 2 commits into
Open
docs: numpy-style docstrings on Favorites endpoint (15 methods)#1855jacalata wants to merge 2 commits into
jacalata wants to merge 2 commits into
Conversation
Copy link
Copy Markdown
Contributor
Sorry, something went wrong.
Adds a class-level docstring plus 15 method docstrings on Favorites (get, add_favorite, 6x add_favorite_<type>, delete_favorite, 6x delete_favorite_<type>). Content ported from docs/api-ref.md's Favorites section on gh-pages so that the Sphinx pipeline in #1832 will produce equivalent output once wired up. Part of the api-ref -> Sphinx migration; see the migration audit report for the full list of methods still needing docstrings. Favorites was the largest single chunk in the "needs_docstring" bucket (15/41 methods). No behavior change. Docs only.
Copy link
Copy Markdown
Sorry, something went wrong.
This was referenced Aug 8, 2026
Copy link
Copy Markdown
There was a problem hiding this comment.
Pull request overview
This PR backfills NumPy-style docstrings for the Favorites endpoint to support upcoming Sphinx-generated API reference output, with the intent of matching the existing handwritten api-ref.md content.
Changes:
- Added a class-level docstring to Favorites describing behavior and storage of retrieved favorites.
- Added NumPy-style docstrings for 15 public endpoint methods covering get/add/delete favorites across supported types.
tableauserverclient/server/endpoint/favorites_endpoint.py:260
- delete_favorite is the polymorphic entry point but its docstring is missing the REST API reference link that the type-specific delete helpers include. Adding a link keeps the generated docs consistent.
type; this method is the polymorphic entry point.
Parameters
tableauserverclient/server/endpoint/favorites_endpoint.py:400
- This docstring is missing a REST API reference link, unlike the other delete_favorite_* helpers. Adding it improves consistency in the generated API reference.
"""Remove a metric from the user's favorites.
Parameters
----------
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Sorry, something went wrong.
Comment thread
tableauserverclient/server/endpoint/favorites_endpoint.py
Outdated
Comment thread
tableauserverclient/server/endpoint/favorites_endpoint.py
- Class docstring: add missing "collections" FavoriteType (7, not 6). - add_favorite: drop misleading #add_workbook_to_favorites anchor on polymorphic method; link to Favorites Methods page root. - add_favorite_metric: add REST API link (#add_metric_to_favorites). - delete_favorite: add REST API link; polymorphic, so page root. - delete_favorite_metric: add REST API link; no per-type anchor exists, so page root. - delete_favorite_flow: fix anchor drift (#delete_flow_from_favorites -> #ref_delete_flow_from_favorites).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation
Favorites was the largest single chunk in the needs-docstring bucket per
the api-ref migration audit (15 of 41 remaining public endpoint methods
without docstrings). Once #1832 wires up Sphinx, the generated output
will cover what the handwritten api-ref.md page does today.
Behavior change
Docs only. No behavior change.
Adds a class-level docstring on Favorites plus 15 method docstrings:
get, add_favorite, 6x add_favorite_<type>, delete_favorite,
6x delete_favorite_<type>. Content ported from the Favorites section of
api-ref.md on gh-pages.
Known asymmetry in the API surface (documented in the docstrings, not
resolved here): add_favorite takes content_type as a plain str with
example values like "workbook"; delete_favorite takes it as a
Resource enum. Callers reading the two side-by-side will notice the
inconsistency.
Test plan
🤖 Generated with Claude Code