[Docs] Add minimal nuxt version to feature/utility - may be a label or a badge

[mkierdev]

Describe the feature

Nuxt 3.9 introduced new utility called callOnce. https://nuxt.com/docs/api/utils/call-once

However, if you are reading that page you have no idea that Nuxt 3.9 is required in order to use that utility. Maybe it would be possible to mark minimal nuxt version for a feature to work? It can be implemented as a badge or label.

This information can be:

• "global" for whole docs page, providing minimalVersion inside frontmatter
• "local" for newly introduced feature extending functionality like getCachedData for useFetch (Nuxt 3.8 if I remember correctly?) https://nuxt.com/docs/api/composables/use-fetch#params

I believe that simple :badge[v3.9] from Docus is more than enough

Additional information

• Would you be willing to help implement this feature?
• Could this feature be implemented as a module?

Final checks

• Read the contribution guide.
• Check existing discussions and issues.

[danielroe]

A great idea - and @Atinux and I have talked about this...

If we can't automate it, then it would be nice to annotate.

[manniL]

I remember this was a topic a few times ago and I'm also all for it. Helpful for upgrading versions or when new (future) features are committed but not released yet 👍🏻

[manniL]

@Atinux not sure if that fully closes the issue as documenting the "first version available" of most features would be nice.

[mkierdev]

callOnce was just an example of how important it is to provide minimal version info across every feature. I understand that it would be impossible to keep versioning whole docs to each nuxt version for various reasons, so this is why a small notice would be helpful.

Small projects can often be up-to-date, but when we talk about large-scale apps with a lot of dependencies it is not so obvious that they can be updated on day 1.

[Atinux]

Sure thing! Happy to re-open it as we can improve the docs along the way for each composable / feature with the minimal version associated to it 👍

[warflash]

Linking #23189

[luc122c]

Hello, this is a great idea! I remember when developing with WordPress they used @since annotations in the docblock. See, for example, the get_block_asset_url function in WordPress. It has an annotation here saying @since 6.4.0 which then shows up in the changelog and also allows for aggregating changes in versions.

It would be easy enough to add @since JSDoc annotations moving forward. It would be time consuming but not too difficult to look back through the changelogs of releases to see when new functions were added. The docs build would need updating to read and reference the versions.

[manniL]

@luc122c An @since would be a nice start, especially because of the utilization for auto-generation. It might not work for everything though (e.g. not for components).

[luc122c]

e.g. not for components

@manniL I've just had a play and although the JSDoc does not show in the IDE, the annotation does carry across to the definition file. Perhaps this is something that could be picked up by an extension (e.g. Volar or Nuxtr)?

[luc122c]

I've started adding @since annotations in #25086; please let me know if I'm on the right track! :)

I've also had a look at how the documentation works, but I'm not sure where we can hook in to read this info and inject it into the docs? I see there are hooks available in unbuild but I'm not sure what they are, or if that's even the right place?

[luc122c]

Roadmap for completing this issue:

• docs(nuxt): add @since annotations to exported composables #25086
• docs: add @since annotations to exported functions #25365
• Add lint rules to catch missing annotations
• Add badges to docs

Please let me know if there are any additional requests/ideas (e.g. annotating components)