For MediaWiki core we do this with simple code comments in Resources.php. See the mediawiki.misc-authed-ooui bundle for example.

For extensions, I suppose extension.json makes sense. On the other hand, writing more than one line of text in JSON is not a great developer experience.

Are some teams doing that already? If so, I wouldn't mind if we start by formalising that indeed as @Tgr suggests.

In T252335#6130292, @Krinkle wrote:

Are some teams doing that already?

Not that I'm aware. We do documentation similarly in the extension.json configuration section or in EventLogging schema pages, for example. (And yes, it's not a great developer experience. Still a lot better than nothing, though.)

In addition to the example @Tgr gave it seems like this would also have helped @Urbanecm_WMF on T344925

@Tgr allowing a @private or @stable property key in ResourceLoader modules would be very helpful here in addition to the existing deprecated key (which also seems like good preparation for T225842).

I would expect modules that are designed for reuse e.g. mediawiki.api to have a stable tag in their definition. This would also be helpful addition to https://www.mediawiki.org/wiki/Stable_interface_policy/Frontend

Example patch:

diff --git a/resources/Resources.php b/resources/Resources.php
index 90a31a26ddb..86265eb1398 100644
--- a/resources/Resources.php
+++ b/resources/Resources.php
@@ -696,6 +696,7 @@ return [
 		],
 	],
 	'mediawiki.api' => [
+		'@stable' => 'For use in gadgets, extensions and skins.',
 		'scripts' => [
 			'resources/src/mediawiki.api/index.js',
 			'resources/src/mediawiki.api/rest.js',
@@ -1972,6 +1973,7 @@ return [
 		],
 	],
 	'mediawiki.special' => [
+		'@stable' => 'For use inside Special pages only.',
 		'styles' => [
 			'resources/src/mediawiki.special/special.less',
 			'resources/src/mediawiki.special/apisandbox.css',
@@ -1993,6 +1995,7 @@ return [
 		],
 	],
 	'mediawiki.special.apisandbox' => [
+		'@private' => 'Only for use inside Special:ApiSandbox',
 		'localBasePath' => MW_INSTALL_PATH . '/resources/src/mediawiki.special.apisandbox',
 		'remoteBasePath' => "$wgResourceBasePath/resources/src/mediawiki.special.apisandbox",
 		'styles' => 'apisandbox.less',

I think '@stable' => 'For use inside Special pages only.' mixes two different things (stability and where to use) in a way that makes it ambiguous (does it mean it should only be used on special pages, or that it's OK to use elsewhere but you should not have any expectations of B/C)? But yeah, some kind of stability indicator seems useful.

Another possible approach would be to have a documentation library like resources/docs and for every module it would be required to have <modulename>.js in that directory, with nothing but a docblock in it. That would be a little more IDE- and documentation generator friendly, maybe, although less obvious.