const env = require( 'jsdoc/env' );
const fs = require( 'jsdoc/fs' );
const helper = require( 'jsdoc/util/templateHelper' );
const logger = require( 'jsdoc/util/logger' );
const path = require( 'jsdoc/path' );
const { taffy } = require( '@jsdoc/salty' );
const template = require( 'jsdoc/template' );
const util = require( 'util' );
const htmlsafe = helper.htmlsafe;
const linkto = helper.linkto;
const resolveAuthorLinks = helper.resolveAuthorLinks;
const hasOwnProp = Object.prototype.hasOwnProperty;
let data;
let view;
let outdir = path.normalize( env.opts.destination );
function mkdirSync( filepath ) {
return fs.mkdirSync( filepath, { recursive: true } );
}
function find( spec ) {
return helper.find( data, spec );
}
function getAncestorLinks( doclet ) {
return helper.getAncestorLinks( data, doclet );
}
function hashToLink( doclet, hash ) {
let url;
if ( ! /^(#.+)/.test( hash ) ) {
return hash;
}
url = helper.createLink( doclet );
url = url.replace( /(#.+|$)/, hash );
return `${hash}`;
}
function needsSignature( { kind, type, meta } ) {
let needsSig = false;
// function and class definitions always get a signature
if ( kind === 'function' || kind === 'class' ) {
needsSig = true;
} else if ( kind === 'typedef' && type && type.names && type.names.length ) {
// typedefs that contain functions get a signature, too
for ( let i = 0, l = type.names.length; i < l; i ++ ) {
if ( type.names[ i ].toLowerCase() === 'function' ) {
needsSig = true;
break;
}
}
} else if ( kind === 'namespace' && meta && meta.code && meta.code.type && meta.code.type.match( /[Ff]unction/ ) ) {
// and namespaces that are functions get a signature (but finding them is a
// bit messy)
needsSig = true;
}
return needsSig;
}
function updateItemName( item ) {
let itemName = item.name || '';
if ( item.variable ) {
itemName = `…${itemName}`;
}
return itemName;
}
function addParamAttributes( params ) {
return params.filter( ( { name } ) => name && ! name.includes( '.' ) ).map( updateItemName );
}
function buildItemTypeStrings( item ) {
const types = [];
if ( item && item.type && item.type.names ) {
item.type.names.forEach( name => {
types.push( linkto( name, htmlsafe( name ) ) );
} );
}
return types;
}
function buildSearchListForData() {
const searchList = [];
data().each( ( item ) => {
if ( item.kind !== 'package' && ! item.inherited ) {
searchList.push( {
title: item.longname,
link: linkto( item.longname, item.name ),
description: item.description,
} );
}
} );
return searchList;
}
function buildAttribsString( attribs ) {
let attribsString = '';
if ( attribs && attribs.length ) {
attribsString = htmlsafe( util.format( '(%s) ', attribs.join( ', ' ) ) );
}
return attribsString;
}
function addNonParamAttributes( items ) {
let types = [];
items.forEach( item => {
types = types.concat( buildItemTypeStrings( item ) );
} );
return types;
}
function addSignatureParams( f ) {
const params = f.params ? addParamAttributes( f.params ) : [];
f.signature = util.format( '%s(%s)', ( f.signature || '' ), params.join( ', ' ) );
}
function addSignatureReturns( f ) {
const attribs = [];
let attribsString = '';
let returnTypes = [];
let returnTypesString = '';
const source = f.yields || f.returns;
// jam all the return-type attributes into an array. this could create odd results (for example,
// if there are both nullable and non-nullable return types), but let's assume that most people
// who use multiple @return tags aren't using Closure Compiler type annotations, and vice-versa.
if ( source ) {
source.forEach( item => {
helper.getAttribs( item ).forEach( attrib => {
if ( ! attribs.includes( attrib ) ) {
attribs.push( attrib );
}
} );
} );
attribsString = buildAttribsString( attribs );
}
if ( source ) {
returnTypes = addNonParamAttributes( source );
}
if ( returnTypes.length ) {
returnTypesString = util.format( ' → %s{%s}', attribsString, returnTypes.join( '|' ) );
}
f.signature = `${f.signature || ''}${returnTypesString}`;
}
function addSignatureTypes( f ) {
const types = f.type ? buildItemTypeStrings( f ) : [];
f.signature = `${f.signature || ''}${types.length ? ` :${types.join( '|' )}` : ''}`;
}
function addAttribs( f ) {
const attribs = helper.getAttribs( f );
const attribsString = buildAttribsString( attribs );
f.attribs = util.format( '%s', attribsString );
}
function shortenPaths( files, commonPrefix ) {
Object.keys( files ).forEach( file => {
files[ file ].shortened = files[ file ].resolved.replace( commonPrefix, '' )
// always use forward slashes
.replace( /\\/g, '/' );
} );
return files;
}
function getPathFromDoclet( { meta } ) {
if ( ! meta ) {
return null;
}
return meta.path && meta.path !== 'null' ?
path.join( meta.path, meta.filename ) :
meta.filename;
}
function generate( title, docs, filename, resolveLinks ) {
let html;
resolveLinks = resolveLinks !== false;
const docData = {
env: env,
title: title,
docs: docs
};
const outpath = path.join( outdir, filename );
html = view.render( 'container.tmpl', docData );
if ( resolveLinks ) {
html = helper.resolveLinks( html ); // turn {@link foo} into foo
}
fs.writeFileSync( outpath, html, 'utf8' );
}
function generateSourceFiles( sourceFiles, encoding = 'utf8' ) {
Object.keys( sourceFiles ).forEach( file => {
let source;
// links are keyed to the shortened path in each doclet's `meta.shortpath` property
const sourceOutfile = helper.getUniqueFilename( sourceFiles[ file ].shortened );
helper.registerLink( sourceFiles[ file ].shortened, sourceOutfile );
try {
source = {
kind: 'source',
code: helper.htmlsafe( fs.readFileSync( sourceFiles[ file ].resolved, encoding ) )
};
} catch ( e ) {
logger.error( 'Error while generating source file %s: %s', file, e.message );
}
generate( `Source: ${sourceFiles[ file ].shortened}`, [ source ], sourceOutfile,
false );
} );
}
function buildClassNav( items, itemsSeen, linktoFn ) {
const coreDirectory = 'src';
const addonsDirectory = 'examples/jsm';
const hierarchy = new Map();
hierarchy.set( 'Core', new Map() );
hierarchy.set( 'Addons', new Map() );
let nav = '';
if ( items.length ) {
items.forEach( item => {
let displayName;
let itemNav = '';
if ( ! hasOwnProp.call( itemsSeen, item.longname ) ) {
if ( env.conf.templates.default.useLongnameInNav ) {
displayName = item.longname;
} else {
displayName = item.name;
}
itemNav += `${linktoFn( item.longname, displayName.replace( /\b(module|event):/g, '' ) )}`;
itemsSeen[ item.longname ] = true;
const path = item.meta.shortpath;
if ( path.startsWith( coreDirectory ) ) {
const subCategory = path.split( '/' )[ 1 ];
pushNavItem( hierarchy, 'Core', subCategory, itemNav );
} else if ( path.startsWith( addonsDirectory ) ) {
const subCategory = path.split( '/' )[ 2 ];
pushNavItem( hierarchy, 'Addons', subCategory, itemNav );
}
}
} );
for ( const [ mainCategory, map ] of hierarchy ) {
nav += `${mainCategory}
`;
for ( const [ subCategory, links ] of map ) {
nav += `${subCategory}
`;
let navItems = '';
for ( const link of links ) {
navItems += link;
}
nav += ``;
}
}
}
return nav;
}
function buildGlobalsNav( globals, seen ) {
let globalNav;
let nav = '';
if ( globals.length ) {
// TSL
let tslNav = '';
globals.forEach( ( { kind, longname, name, tags } ) => {
if ( kind !== 'typedef' && ! hasOwnProp.call( seen, longname ) && Array.isArray( tags ) && tags[ 0 ].title === 'tsl' ) {
tslNav += `${linkto( longname, name )}`;
seen[ longname ] = true;
}
} );
nav += `TSL
`;
// Globals
globalNav = '';
globals.forEach( ( { kind, longname, name } ) => {
if ( kind !== 'typedef' && ! hasOwnProp.call( seen, longname ) ) {
globalNav += `${linkto( longname, name )}`;
}
seen[ longname ] = true;
} );
if ( ! globalNav ) {
// turn the heading into a link so you can actually get to the global page
nav += `${linkto( 'global', 'Global' )}
`;
} else {
nav += `Global
`;
}
}
return nav;
}
function pushNavItem( hierarchy, mainCategory, subCategory, itemNav ) {
subCategory = subCategory[ 0 ].toUpperCase() + subCategory.slice( 1 ); // capitalize
if ( hierarchy.get( mainCategory ).get( subCategory ) === undefined ) {
hierarchy.get( mainCategory ).set( subCategory, [] );
}
const categoryList = hierarchy.get( mainCategory ).get( subCategory );
categoryList.push( itemNav );
}
/**
* Create the navigation sidebar.
* @param {object} members The members that will be used to create the sidebar.
* @param {array