Updates to docs

Author: gkjohnson

src/babylonjs/renderer/API.md

@@ -36,7 +36,7 @@ constructor( scene: Scene )
 ### .parse
 
 ```js
-parse( buffer: ArrayBuffer, uri: string ): Promise<Object>
+async parse( buffer: ArrayBuffer, uri: string ): Promise<Object>
 ```
 
 
@@ -75,7 +75,7 @@ constructor( scene: Scene )
 ### .parse
 
 ```js
-parse(
+async parse(
 	buffer: ArrayBuffer,
 	uri: string,
 	extension: string

src/three/plugins/API.md

@@ -857,11 +857,11 @@ for how to obtain these values.
 ### .getPropertyTextureDataAsync
 
 ```js
-getPropertyTextureDataAsync(
+async getPropertyTextureDataAsync(
 	triangle: number,
 	barycoord: Vector3,
 	target = []: Array
-): Promise<Array>
+): Array
 ```
 
 Returns the same data as `getPropertyTextureData` but performs texture reads

src/three/plugins/gltf/metadata/classes/StructuralMetadata.js

@@ -170,7 +170,7 @@ export class StructuralMetadata {
 	 * @param {number} triangle Triangle index from a raycast hit.
 	 * @param {Vector3} barycoord Barycentric coordinate of the hit point.
 	 * @param {Array} [target=[]] Optional target array to write into.
-	 * @returns {Promise<Array>}
+	 * @returns {Array}
 	 */
 	async getPropertyTextureDataAsync( triangle, barycoord, target = [] ) {
 

utils/docs/RenderDocsUtils.js

@@ -309,8 +309,9 @@ function renderCallable( doc, heading, sigPrefix, callbackMap ) {
 export function renderMethod( doc, callbackMap = {} ) {
 
 	const isStatic = doc.scope === 'static';
-	const prefix = isStatic ? 'static ' : '';
-	return renderCallable( doc, `### ${ prefix }.${ doc.name }`, prefix, callbackMap );
+	const headingPrefix = isStatic ? 'static ' : '';
+	const sigPrefix = isStatic ? `static ${ doc.async ? 'async ' : '' }` : ( doc.async ? 'async ' : '' );
+	return renderCallable( doc, `### ${ headingPrefix }.${ doc.name }`, sigPrefix, callbackMap );
 
 }
 

utils/docs/build.js

@@ -40,10 +40,19 @@ const ENTRY_POINTS = [
 ];
 
 // Run JSDoc for all entry points and build a global type registry for cross-file links
-const results = ENTRY_POINTS.map( entry => ( {
-	entry,
-	jsdoc: filterDocumented( runJsDoc( path.resolve( ROOT_DIR, entry.source ) ) )
-} ) );
+const results = ENTRY_POINTS.map( entry => {
+
+	let jsdoc = filterDocumented( runJsDoc( path.resolve( ROOT_DIR, entry.source ) ) );
+	if ( entry.exclude ) {
+
+		const excludePath = path.resolve( ROOT_DIR, entry.exclude );
+		jsdoc = jsdoc.filter( d => ! d.meta || ! d.meta.path || ! d.meta.path.startsWith( excludePath ) );
+
+	}
+
+	return { entry, jsdoc };
+
+} );
 
 // Doclet type predicates
 const isClass = d => d.kind === 'class';
@@ -69,7 +78,8 @@ for ( const { entry, jsdoc } of results ) {
 
 }
 
-// Pass 2: render each entry point.
+// Pass 2: render each entry point and accumulate sections per output file.
+const outputSections = {}; // output file -> accumulated sections array
 for ( const { entry, jsdoc } of results ) {
 
 	const resolveLink = name => {
@@ -173,7 +183,7 @@ for ( const { entry, jsdoc } of results ) {
 
 	}
 
-	// construct the readme files
+	// construct sections for this entry point
 	const sections = [ `# ${ entry.title }`, '' ];
 
 	for ( const [ groupName, consts ] of Object.entries( constsByGroup ) ) {
@@ -207,23 +217,23 @@ for ( const { entry, jsdoc } of results ) {
 
 	}
 
-	const header = '<!-- This file is generated automatically. Do not edit it directly. -->\n';
-	const output = header + resolveLinks( sections.join( '\n' ) );
-	fs.writeFileSync( path.join( ROOT_DIR, entry.output ), output );
-	console.log( `Written: ${ entry.output }` );
+	if ( ! outputSections[ entry.output ] ) outputSections[ entry.output ] = [];
+	outputSections[ entry.output ].push( ...sections );
 
 }
 
-//
-
-function runJsDoc( source ) {
+// Write each output file once, after all entry points have been processed.
+const header = '<!-- This file is generated automatically. Do not edit it directly. -->\n';
+for ( const [ outputFile, sections ] of Object.entries( outputSections ) ) {
 
-	// Default maxBuffer is 1 MB; large source directories can exceed that, so raise it to 32 MB.
-	const result = execSync( `npx jsdoc -X -r "${ source }"`, { maxBuffer: 32 * 1024 * 1024 } ).toString();
-	return JSON.parse( result );
+	const output = header + resolveLinks( sections.join( '\n' ) );
+	fs.writeFileSync( path.join( ROOT_DIR, outputFile ), output );
+	console.log( `Written: ${ outputFile }` );
 
 }
 
+//
+
 function groupByTag( docs, predicate, defaultGroup ) {
 
 	const groups = {};
@@ -240,6 +250,14 @@ function groupByTag( docs, predicate, defaultGroup ) {
 
 }
 
+function runJsDoc( source ) {
+
+	// Default maxBuffer is 1 MB; large source directories can exceed that, so raise it to 32 MB.
+	const result = execSync( `npx jsdoc -X -r "${ source }"`, { maxBuffer: 32 * 1024 * 1024 } ).toString();
+	return JSON.parse( result );
+
+}
+
 // Topological sort: every parent class appears before its subclasses.
 // Siblings (subclasses sharing the same parent) are kept together and ordered alphabetically.
 function topologicalSortClasses( classes ) {