docs(ai): Document enum values in top-level JSDoc comments #9271
Conversation
|
Size Report 1Affected ProductsNo changes between base commit (ccbf7ba) and merge commit (8057046).Test Logs |
Size Analysis Report 1Affected ProductsNo changes between base commit (ccbf7ba) and merge commit (8057046).Test Logs |
There was a problem hiding this comment.
Unless I'm misunderstanding, removing the comments above the type unions actually does remove strings from devsite. There's two sections in devsite docs, Variables and Type Aliases, and the consts go under Variables and the string unions go under Type Aliases. That's not great but not really changeable without messing with api-documenter. They both have the same anchor name so if you click on one in the table of contents, you'll only go to the first one (under Variables), but the other one also exists and people could run into it by scrolling, or the short description in the table of contents.
| An enum-like object containing constants that represent the supported backends for the Firebase AI SDK. | ||
|
|
||
| These values are assigned to the `backendType` property within the specific backend configuration objects ([GoogleAIBackend](./ai.googleaibackend.md#googleaibackend_class) or [VertexAIBackend](./ai.vertexaibackend.md#vertexaibackend_class)<!-- -->) to identify which service to target. | ||
| This determines which backend service (Vertex AI Gemini API or Gemini Developer API) the SDK will communicate with. These values are assigned to the `backendType` property within the specific backend configuration objects ([GoogleAIBackend](./ai.googleaibackend.md#googleaibackend_class) or [VertexAIBackend](./ai.vertexaibackend.md#vertexaibackend_class)<!-- -->) to identify which service to target. <br/> <b>VERTEX\_AI:</b> Identifies the backend service for the Vertex AI Gemini API provided through Google Cloud. Use this constant when creating a [VertexAIBackend](./ai.vertexaibackend.md#vertexaibackend_class) configuration. <br/> <b>GOOGLE\_AI:</b> Identifies the backend service for the Gemini Developer API ([Google AI](https://ai.google/)<!-- -->). Use this constant when creating a [GoogleAIBackend](./ai.googleaibackend.md#googleaibackend_class) configuration. |
There was a problem hiding this comment.
Could we please remove this: ([Google AI](https://ai.google/)
Wherever possible and if a docs link is needed, we should link into the Firebase docs rather than the underlying Gemini API provider docs.
If you need a place to link to for differentiation, you can link here: https://firebase.google.com/docs/ai-logic/faq-and-troubleshooting#differences-between-gemini-api-providers
| To specify an aspect ratio for generated images, set the `aspectRatio` property in your [ImagenGenerationConfig](./ai.imagengenerationconfig.md#imagengenerationconfig_interface)<!-- -->. | ||
|
|
||
| See the [documentation](http://firebase.google.com/docs/vertex-ai/generate-images) for more details and examples of the supported aspect ratios. | ||
| To specify an aspect ratio for generated images, set the `aspectRatio` property in your [ImagenGenerationConfig](./ai.imagengenerationconfig.md#imagengenerationconfig_interface)<!-- -->. See the [documentation](http://firebase.google.com/docs/vertex-ai/generate-images) for more details and examples of the supported aspect ratios. |
There was a problem hiding this comment.
Should this link to here?
https://firebase.google.com/docs/ai-logic/generate-images-imagen
or if you'd like, more specifically here: https://firebase.google.com/docs/ai-logic/generate-images-imagen#specs-and-limitations
4 participants
This fixes an issue with the documentation on DevSite, where enum values' JSDoc strings aren't extracted by our API documenter tool. For example, the
ImagenPersonFilterLeveldocs don't contain docs for each enum value, despite those explanations being in the source code here.I removed all documentation from the type union declarations (
type x = (typeof x..), because 1) they're not used by API documenter so they aren't in devsite, 2) VSCode type hints inherit the docs of the type union from the object:(here we're hovering the definition of a
HarmCategorytype union, and we see the docs for theHarmCategoryobject)