JSDoc: Add import section for addons. (#30853)

examples/jsm/controls/OrbitControls.js

@@ -83,6 +83,7 @@ const _EPS = 0.000001;
  * ```
  *
  * @augments Controls
+ * @three_import import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
  */
 class OrbitControls extends Controls {
 

examples/jsm/utils/BufferGeometryUtils.js

@@ -11,7 +11,10 @@ import {
 	Vector3,
 } from 'three';
 
-/** @module BufferGeometryUtils */
+/**
+ * @module BufferGeometryUtils
+ * @three_import import * as BufferGeometryUtils from 'three/addons/utils/BufferGeometryUtils.js';
+ */
 
 /**
  * Computes vertex tangents using the MikkTSpace algorithm. MikkTSpace generates the same tangents consistently,

utils/docs/template/publish.js

@@ -432,11 +432,17 @@ function buildGlobalsNav( globals, seen ) {
 
 		globals.forEach( ( { kind, longname, name, tags } ) => {
 
-			if ( kind !== 'typedef' && ! hasOwnProp.call( seen, longname ) && Array.isArray( tags ) && tags[ 0 ].title === 'tsl' ) {
+			if ( kind !== 'typedef' && ! hasOwnProp.call( seen, longname ) && Array.isArray( tags ) ) {
 
-				tslNav += `<li data-name="${longname}">${linkto( longname, name )}</li>`;
+				const tslTag = tags.find( tag => tag.title === 'tsl' );
 
-				seen[ longname ] = true;
+				if ( tslTag !== undefined ) {
+
+					tslNav += `<li data-name="${longname}">${linkto( longname, name )}</li>`;
+
+					seen[ longname ] = true;
+
+				}
 
 			}
 
@@ -705,6 +711,24 @@ exports.publish = ( taffyData, opts, tutorials ) => {
 
 	} );
 
+	// prepare import statements
+	data().each( doclet => {
+
+		if ( doclet.kind === 'class' || doclet.kind === 'module' ) {
+
+			const tags = doclet.tags;
+
+			if ( Array.isArray( tags ) ) {
+
+				const importTag = tags.find( tag => tag.title === 'three_import' );
+				doclet.import = ( importTag !== undefined ) ? importTag.text : null;
+
+			}
+
+		}
+
+	} );
+
 	const members = helper.getMembers( data );
 	members.tutorials = tutorials.children;
 

utils/docs/template/tmpl/container.tmpl

@@ -65,6 +65,12 @@
         <?js= self.partial('augments.tmpl', doc) ?>
     <?js } ?>
 
+    <?js if (doc.import) { ?>
+        <h3 class="subsection-title">Import</h3>
+        <?js= doc.name ?> is an addon, and must be imported explicitly, see <a href="https://threejs.org/manual/#en/installation" target="_blank">Installation#Addons</a>.
+        <pre class="prettyprint source lang-js"><code><?js= doc.import ?></code></pre>
+    <?js } ?>
+
     <?js if (doc.requires && doc.requires.length) { ?>
         <h3 class="subsection-title">Requires</h3>