From be1c7e50e1e8809ea56f2c9d472eccd8ffd73a97 Mon Sep 17 00:00:00 2001
From: Daniel Baumann <daniel.baumann@progress-linux.org>
Date: Fri, 19 Apr 2024 04:57:58 +0200
Subject: Adding upstream version 1.44.3.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
---
 .../misc/oktavia/templates/jsdoc3/publish.js       | 508 +++++++++++++++++++++
 1 file changed, 508 insertions(+)
 create mode 100644 web/server/h2o/libh2o/misc/oktavia/templates/jsdoc3/publish.js

(limited to 'web/server/h2o/libh2o/misc/oktavia/templates/jsdoc3/publish.js')

diff --git a/web/server/h2o/libh2o/misc/oktavia/templates/jsdoc3/publish.js b/web/server/h2o/libh2o/misc/oktavia/templates/jsdoc3/publish.js
new file mode 100644
index 00000000..36211462
--- /dev/null
+++ b/web/server/h2o/libh2o/misc/oktavia/templates/jsdoc3/publish.js
@@ -0,0 +1,508 @@
+/*global env: true */
+var template = require('jsdoc/template'),
+    fs = require('jsdoc/fs'),
+    path = require('jsdoc/path'),
+    taffy = require('taffydb').taffy,
+    handle = require('jsdoc/util/error').handle,
+    helper = require('jsdoc/util/templateHelper'),
+    htmlsafe = helper.htmlsafe,
+    linkto = helper.linkto,
+    resolveAuthorLinks = helper.resolveAuthorLinks,
+    scopeToPunc = helper.scopeToPunc,
+    hasOwnProp = Object.prototype.hasOwnProperty,
+    data,
+    view,
+    outdir = env.opts.destination;
+
+
+function find(spec) {
+    return helper.find(data, spec);
+}
+
+function tutoriallink(tutorial) {
+    return helper.toTutorial(tutorial, null, { tag: 'em', classname: 'disabled', prefix: 'Tutorial: ' });
+}
+
+function getAncestorLinks(doclet) {
+    return helper.getAncestorLinks(data, doclet);
+}
+
+function hashToLink(doclet, hash) {
+    if ( !/^(#.+)/.test(hash) ) { return hash; }
+
+    var url = helper.createLink(doclet);
+
+    url = url.replace(/(#.+|$)/, hash);
+    return '<a href="' + url + '">' + hash + '</a>';
+}
+
+function needsSignature(doclet) {
+    var needsSig = false;
+
+    // function and class definitions always get a signature
+    if (doclet.kind === 'function' || doclet.kind === 'class') {
+        needsSig = true;
+    }
+    // typedefs that contain functions get a signature, too
+    else if (doclet.kind === 'typedef' && doclet.type && doclet.type.names &&
+        doclet.type.names.length) {
+        for (var i = 0, l = doclet.type.names.length; i < l; i++) {
+            if (doclet.type.names[i].toLowerCase() === 'function') {
+                needsSig = true;
+                break;
+            }
+        }
+    }
+
+    return needsSig;
+}
+
+function addSignatureParams(f) {
+    var params = helper.getSignatureParams(f, 'optional');
+
+    f.signature = (f.signature || '') + '('+params.join(', ')+')';
+}
+
+function addSignatureReturns(f) {
+    var returnTypes = helper.getSignatureReturns(f);
+
+    f.signature = '<span class="signature">'+(f.signature || '') + '</span>' + '<span class="type-signature">'+(returnTypes.length? ' &rarr; {'+returnTypes.join('|')+'}' : '')+'</span>';
+}
+
+function addSignatureTypes(f) {
+    var types = helper.getSignatureTypes(f);
+
+    f.signature = (f.signature || '') + '<span class="type-signature">'+(types.length? ' :'+types.join('|') : '')+'</span>';
+}
+
+function addAttribs(f) {
+    var attribs = helper.getAttribs(f);
+
+    f.attribs = '<span class="type-signature">'+htmlsafe(attribs.length? '<'+attribs.join(', ')+'> ' : '')+'</span>';
+}
+
+function shortenPaths(files, commonPrefix) {
+    // always use forward slashes
+    var regexp = new RegExp('\\\\', 'g');
+
+    Object.keys(files).forEach(function(file) {
+        files[file].shortened = files[file].resolved.replace(commonPrefix, '')
+            .replace(regexp, '/');
+    });
+
+    return files;
+}
+
+function resolveSourcePath(filepath) {
+    return path.resolve(process.cwd(), filepath);
+}
+
+function getPathFromDoclet(doclet) {
+    if (!doclet.meta) {
+        return;
+    }
+
+    var filepath = doclet.meta.path && doclet.meta.path !== 'null' ?
+        doclet.meta.path + '/' + doclet.meta.filename :
+        doclet.meta.filename;
+
+    return filepath;
+}
+
+function generate(title, docs, filename, resolveLinks) {
+    resolveLinks = resolveLinks === false ? false : true;
+
+    var docData = {
+        title: title,
+        docs: docs
+    };
+
+    var outpath = path.join(outdir, filename),
+        html = view.render('container.tmpl', docData);
+
+    if (resolveLinks) {
+        html = helper.resolveLinks(html); // turn {@link foo} into <a href="foodoc.html">foo</a>
+    }
+
+    fs.writeFileSync(outpath, html, 'utf8');
+}
+
+function generateSourceFiles(sourceFiles) {
+    Object.keys(sourceFiles).forEach(function(file) {
+        var source;
+        // links are keyed to the shortened path in each doclet's `meta.filename` property
+        var sourceOutfile = helper.getUniqueFilename(sourceFiles[file].shortened);
+        helper.registerLink(sourceFiles[file].shortened, sourceOutfile);
+
+        try {
+            source = {
+                kind: 'source',
+                code: helper.htmlsafe( fs.readFileSync(sourceFiles[file].resolved, 'utf8') )
+            };
+        }
+        catch(e) {
+            handle(e);
+        }
+
+        generate('Source: ' + sourceFiles[file].shortened, [source], sourceOutfile,
+            false);
+    });
+}
+
+/**
+ * Create the navigation sidebar.
+ * @param {object} members The members that will be used to create the sidebar.
+ * @param {array<object>} members.classes
+ * @param {array<object>} members.externals
+ * @param {array<object>} members.globals
+ * @param {array<object>} members.mixins
+ * @param {array<object>} members.modules
+ * @param {array<object>} members.namespaces
+ * @param {array<object>} members.tutorials
+ * @param {array<object>} members.events
+ * @return {string} The HTML for the navigation sidebar.
+ */
+function buildNav(members) {
+    var nav = '<h2><a href="index.html">Index</a></h2>',
+        seen = {};
+
+    if (members.modules.length) {
+        nav += '<h3>Modules</h3><ul>';
+        members.modules.forEach(function(m) {
+            if ( !hasOwnProp.call(seen, m.longname) ) {
+                nav += '<li>'+linkto(m.longname, m.name)+'</li>';
+            }
+            seen[m.longname] = true;
+        });
+
+        nav += '</ul>';
+    }
+
+    if (members.externals.length) {
+        nav += '<h3>Externals</h3><ul>';
+        members.externals.forEach(function(e) {
+            if ( !hasOwnProp.call(seen, e.longname) ) {
+                nav += '<li>'+linkto( e.longname, e.name.replace(/(^"|"$)/g, '') )+'</li>';
+            }
+            seen[e.longname] = true;
+        });
+
+        nav += '</ul>';
+    }
+
+    if (members.classes.length) {
+        var moduleClasses = 0;
+        members.classes.forEach(function(c) {
+            var moduleSameName = find({kind: 'module', longname: c.longname});
+            if (moduleSameName.length) {
+                c.name = c.name.replace('module:', 'require("')+'")';
+                moduleClasses++;
+                moduleSameName[0].module = c;
+            }
+            if (moduleClasses !== -1 && moduleClasses < members.classes.length) {
+                nav += '<h3>Classes</h3><ul>';
+                moduleClasses = -1;
+            }
+            if ( !hasOwnProp.call(seen, c.longname) ) {
+                nav += '<li>'+linkto(c.longname, c.name)+'</li>';
+            }
+            seen[c.longname] = true;
+        });
+
+        nav += '</ul>';
+    }
+
+    if (members.events.length) {
+        nav += '<h3>Events</h3><ul>';
+        members.events.forEach(function(e) {
+            if ( !hasOwnProp.call(seen, e.longname) ) {
+                nav += '<li>'+linkto(e.longname, e.name)+'</li>';
+            }
+            seen[e.longname] = true;
+        });
+
+        nav += '</ul>';
+    }
+
+    if (members.namespaces.length) {
+        nav += '<h3>Namespaces</h3><ul>';
+        members.namespaces.forEach(function(n) {
+            if ( !hasOwnProp.call(seen, n.longname) ) {
+                nav += '<li>'+linkto(n.longname, n.name)+'</li>';
+            }
+            seen[n.longname] = true;
+        });
+
+        nav += '</ul>';
+    }
+
+    if (members.mixins.length) {
+        nav += '<h3>Mixins</h3><ul>';
+        members.mixins.forEach(function(m) {
+            if ( !hasOwnProp.call(seen, m.longname) ) {
+                nav += '<li>'+linkto(m.longname, m.name)+'</li>';
+            }
+            seen[m.longname] = true;
+        });
+
+        nav += '</ul>';
+    }
+
+    if (members.tutorials.length) {
+        nav += '<h3>Tutorials</h3><ul>';
+        members.tutorials.forEach(function(t) {
+            nav += '<li>'+tutoriallink(t.name)+'</li>';
+        });
+
+        nav += '</ul>';
+    }
+
+    if (members.globals.length) {
+        nav += '<h3>Global</h3><ul>';
+        members.globals.forEach(function(g) {
+            if ( g.kind !== 'typedef' && !hasOwnProp.call(seen, g.longname) ) {
+                nav += '<li>'+linkto(g.longname, g.name)+'</li>';
+            }
+            seen[g.longname] = true;
+        });
+
+        nav += '</ul>';
+    }
+
+    return nav;
+}
+
+
+/**
+    @param {TAFFY} taffyData See <http://taffydb.com/>.
+    @param {object} opts
+    @param {Tutorial} tutorials
+ */
+exports.publish = function(taffyData, opts, tutorials) {
+    data = taffyData;
+
+    var conf = env.conf.templates || {};
+    conf['default'] = conf['default'] || {};
+
+    var templatePath = opts.template;
+    view = new template.Template(templatePath + '/tmpl');
+
+    // claim some special filenames in advance, so the All-Powerful Overseer of Filename Uniqueness
+    // doesn't try to hand them out later
+    var indexUrl = helper.getUniqueFilename('index');
+    // don't call registerLink() on this one! 'index' is also a valid longname
+
+    var globalUrl = helper.getUniqueFilename('global');
+    helper.registerLink('global', globalUrl);
+
+    // set up templating
+    view.layout = 'layout.tmpl';
+
+    // set up tutorials for helper
+    helper.setTutorials(tutorials);
+
+    data = helper.prune(data);
+    data.sort('longname, version, since');
+
+    var sourceFiles = {};
+    var sourceFilePaths = [];
+    data().each(function(doclet) {
+         doclet.attribs = '';
+
+        if (doclet.examples) {
+            doclet.examples = doclet.examples.map(function(example) {
+                var caption, code;
+
+                if (example.match(/^\s*<caption>([\s\S]+?)<\/caption>(\s*[\n\r])([\s\S]+)$/i)) {
+                    caption = RegExp.$1;
+                    code    = RegExp.$3;
+                }
+
+                return {
+                    caption: caption || '',
+                    code: code || example
+                };
+            });
+        }
+        if (doclet.see) {
+            doclet.see.forEach(function(seeItem, i) {
+                doclet.see[i] = hashToLink(doclet, seeItem);
+            });
+        }
+
+        // build a list of source files
+        var sourcePath;
+        var resolvedSourcePath;
+        if (doclet.meta) {
+            sourcePath = getPathFromDoclet(doclet);
+            resolvedSourcePath = resolveSourcePath(sourcePath);
+            sourceFiles[sourcePath] = {
+                resolved: resolvedSourcePath,
+                shortened: null
+            };
+            sourceFilePaths.push(resolvedSourcePath);
+        }
+    });
+
+    // update outdir if necessary, then create outdir
+    var packageInfo = ( find({kind: 'package'}) || [] ) [0];
+    if (packageInfo && packageInfo.name) {
+        outdir = path.join(outdir, packageInfo.name, packageInfo.version);
+    }
+    fs.mkPath(outdir);
+
+    // copy static files to outdir
+    var fromDir = path.join(templatePath, 'static'),
+        staticFiles = fs.ls(fromDir, 3);
+
+    staticFiles.forEach(function(fileName) {
+        var toDir = fs.toDir( fileName.replace(fromDir, outdir) );
+        fs.mkPath(toDir);
+        fs.copyFileSync(fileName, toDir);
+    });
+
+    if (sourceFilePaths.length) {
+        sourceFiles = shortenPaths( sourceFiles, path.commonPrefix(sourceFilePaths) );
+    }
+    data().each(function(doclet) {
+        var url = helper.createLink(doclet);
+        helper.registerLink(doclet.longname, url);
+
+        // replace the filename with a shortened version of the full path
+        var docletPath;
+        if (doclet.meta) {
+            docletPath = getPathFromDoclet(doclet);
+            docletPath = sourceFiles[docletPath].shortened;
+            if (docletPath) {
+                doclet.meta.filename = docletPath;
+            }
+        }
+    });
+
+    data().each(function(doclet) {
+        var url = helper.longnameToUrl[doclet.longname];
+
+        if (url.indexOf('#') > -1) {
+            doclet.id = helper.longnameToUrl[doclet.longname].split(/#/).pop();
+        }
+        else {
+            doclet.id = doclet.name;
+        }
+
+        if ( needsSignature(doclet) ) {
+            addSignatureParams(doclet);
+            addSignatureReturns(doclet);
+            addAttribs(doclet);
+        }
+    });
+
+    // do this after the urls have all been generated
+    data().each(function(doclet) {
+        doclet.ancestors = getAncestorLinks(doclet);
+
+        if (doclet.kind === 'member') {
+            addSignatureTypes(doclet);
+            addAttribs(doclet);
+        }
+
+        if (doclet.kind === 'constant') {
+            addSignatureTypes(doclet);
+            addAttribs(doclet);
+            doclet.kind = 'member';
+        }
+    });
+
+    var members = helper.getMembers(data);
+    members.tutorials = tutorials.children;
+
+    // add template helpers
+    view.find = find;
+    view.linkto = linkto;
+    view.resolveAuthorLinks = resolveAuthorLinks;
+    view.tutoriallink = tutoriallink;
+    view.htmlsafe = htmlsafe;
+
+    // once for all
+    view.nav = buildNav(members);
+
+    // only output pretty-printed source files if requested; do this before generating any other
+    // pages, so the other pages can link to the source files
+    if (conf['default'].outputSourceFiles) {
+        generateSourceFiles(sourceFiles);
+    }
+
+    if (members.globals.length) { generate('Global', [{kind: 'globalobj'}], globalUrl); }
+
+    // index page displays information from package.json and lists files
+    var files = find({kind: 'file'}),
+        packages = find({kind: 'package'});
+
+    generate('Index',
+        packages.concat(
+            [{kind: 'mainpage', readme: opts.readme, longname: (opts.mainpagetitle) ? opts.mainpagetitle : 'Main Page'}]
+        ).concat(files),
+    indexUrl);
+
+    // set up the lists that we'll use to generate pages
+    var classes = taffy(members.classes);
+    var modules = taffy(members.modules);
+    var namespaces = taffy(members.namespaces);
+    var mixins = taffy(members.mixins);
+    var externals = taffy(members.externals);
+
+    for (var longname in helper.longnameToUrl) {
+        if ( hasOwnProp.call(helper.longnameToUrl, longname) ) {
+            var myClasses = helper.find(classes, {longname: longname});
+            if (myClasses.length) {
+                generate('Class: ' + myClasses[0].name, myClasses, helper.longnameToUrl[longname]);
+            }
+
+            var myModules = helper.find(modules, {longname: longname});
+            if (myModules.length) {
+                generate('Module: ' + myModules[0].name, myModules, helper.longnameToUrl[longname]);
+            }
+
+            var myNamespaces = helper.find(namespaces, {longname: longname});
+            if (myNamespaces.length) {
+                generate('Namespace: ' + myNamespaces[0].name, myNamespaces, helper.longnameToUrl[longname]);
+            }
+
+            var myMixins = helper.find(mixins, {longname: longname});
+            if (myMixins.length) {
+                generate('Mixin: ' + myMixins[0].name, myMixins, helper.longnameToUrl[longname]);
+            }
+
+            var myExternals = helper.find(externals, {longname: longname});
+            if (myExternals.length) {
+                generate('External: ' + myExternals[0].name, myExternals, helper.longnameToUrl[longname]);
+            }
+        }
+    }
+
+    // TODO: move the tutorial functions to templateHelper.js
+    function generateTutorial(title, tutorial, filename) {
+        var tutorialData = {
+            title: title,
+            header: tutorial.title,
+            content: tutorial.parse(),
+            children: tutorial.children
+        };
+
+        var tutorialPath = path.join(outdir, filename),
+            html = view.render('tutorial.tmpl', tutorialData);
+
+        // yes, you can use {@link} in tutorials too!
+        html = helper.resolveLinks(html); // turn {@link foo} into <a href="foodoc.html">foo</a>
+
+        fs.writeFileSync(tutorialPath, html, 'utf8');
+    }
+
+    // tutorials can have only one parent so there is no risk for loops
+    function saveChildren(node) {
+        node.children.forEach(function(child) {
+            generateTutorial('Tutorial: ' + child.title, child, helper.tutorialToUrl(child.name));
+            saveChildren(child);
+        });
+    }
+    saveChildren(tutorials);
+};
-- 
cgit v1.2.3