docs(instrumentation): better docs for supportedVersions option

experimental/CHANGELOG.md

@@ -31,6 +31,7 @@ All notable changes to experimental packages in this project will be documented
 
 ### :books: (Refine Doc)
 
+* docs(instrumentation): better docs for supportedVersions option [#4693](https://github.com/open-telemetry/opentelemetry-js/pull/4693) @blumamir
 * docs: align all supported versions to a common format [#4696](https://github.com/open-telemetry/opentelemetry-js/pull/4696) @blumamir
 
 ### :house: (Internal)

experimental/packages/opentelemetry-instrumentation/src/types.ts

@@ -88,7 +88,19 @@ export interface InstrumentationModuleFile {
 
  moduleExports?: unknown;
 
- /** Supported version this file */
+ /** Supported versions for the file.
+ *
+ * A module version is supported if one of the supportedVersions in the array satisfies the module version.
+ * The syntax of the version is checked with the `satisfies` function of "The semantic versioner for npm", see
+ * [`semver` package](https://www.npmjs.com/package/semver)
+ * If the version is not supported, we won't apply instrumentation patch.
+ * If omitted, all versions of the module will be patched.
+ *
+ * It is recommended to always specify a range that is bound to a major version, to avoid breaking changes.
+ * New major versions should be reviewed and tested before being added to the supportedVersions array.
+ *
+ * Example: ['>=1.2.3 <3']
+ */
  supportedVersions: string[];
 
  /** Method to patch the instrumentation */
@@ -108,7 +120,19 @@ export interface InstrumentationModuleDefinition {
  /** Instrumented module version */
  moduleVersion?: string;
 
- /** Supported version of module */
+ /** Supported version of module.
+ *
+ * A module version is supported if one of the supportedVersions in the array satisfies the module version.
+ * The syntax of the version is checked with the `satisfies` function of "The semantic versioner for npm", see
+ * [`semver` package](https://www.npmjs.com/package/semver)
+ * If the version is not supported, we won't apply instrumentation patch (see `enable` method).
+ * If omitted, all versions of the module will be patched.
+ *
+ * It is recommended to always specify a range that is bound to a major version, to avoid breaking changes.
+ * New major versions should be reviewed and tested before being added to the supportedVersions array.
+ *
+ * Example: ['>=1.2.3 <3']
+ */
  supportedVersions: string[];
 
  /** Module internal files to be patched */