Fixed miscellaneous jsdoc comments

- this helps tsserver figure out what the type of things is around our
  codebase
- nothing crazy, mostly Express types for the middleware, application and router levels

ghost/api-framework/lib/http.js

@@ -11,9 +11,14 @@ const headers = require('./headers');
  * The wrapper receives the express request, prepares the frame and forwards the request to the pipeline.
  *
  * @param {Function} apiImpl - Pipeline wrapper, which executes the target ctrl function.
- * @return {Function}
+ * @return {import('express').RequestHandler}
  */
 const http = (apiImpl) => {
+    /**
+     * @param {import('express').Request} req - Express request object.
+     * @param {import('express').Response} res - Express response object.
+     * @param {import('express').NextFunction} next - Express next function.
+     */
     return async function Http(req, res, next) {
         debug(`External API request to ${req.url}`);
         let apiKey = null;

ghost/core/core/server/GhostServer.js

@@ -67,7 +67,7 @@ class GhostServer {
      * Starts the ghost server listening on the configured port.
      * Requires an express app to be passed in
      *
-     * @param  {Object} rootApp - Required express app instance.
+     * @param  {import('express').Application} rootApp - Required express app instance.
      * @return {Promise} Resolves once Ghost has started
      */
     start(rootApp) {

ghost/core/core/server/web/admin/app.js

@@ -10,6 +10,10 @@ const errorHandler = require('@tryghost/mw-error-handler');
 const sentry = require('../../../shared/sentry');
 const redirectAdminUrls = require('./middleware/redirect-admin-urls');
 
+/**
+ *
+ * @returns {import('express').Application}
+ */
 module.exports = function setupAdminApp() {
     debug('Admin setup start');
     const adminApp = express('admin');

ghost/core/core/server/web/admin/controller.js

@@ -20,8 +20,8 @@ const messages = {
  *
  * Every request to the admin panel will re-trigger the update check service.
  *
- * @param req
- * @param res
+ * @param {import('express').Request} req
+ * @param {import('express').Response} res
  */
 module.exports = function adminController(req, res) {
     debug('index called');

ghost/core/core/server/web/admin/middleware/redirect-admin-urls.js

@@ -1,5 +1,11 @@
 const urlUtils = require('../../../../shared/url-utils');
 
+/**
+ *
+ * @param {import('express').Request} req
+ * @param {import('express').Response} res
+ * @param {import('express').NextFunction} next
+ */
 function redirectAdminUrls(req, res, next) {
     const subdir = urlUtils.getSubdir();
     const ghostPathRegex = new RegExp(`^${subdir}/ghost/(.+)`);

ghost/core/core/server/web/announcement/routes.js

@@ -3,6 +3,9 @@ const api = require('../../api').endpoints;
 const {http} = require('@tryghost/api-framework');
 const shared = require('../shared');
 
+/**
+ * @returns {import('express').Router}
+ */
 module.exports = function apiRoutes() {
     const router = express.Router('announcements');
 

ghost/core/core/server/web/api/app.js

@@ -5,6 +5,9 @@ const sentry = require('../../../shared/sentry');
 const errorHandler = require('@tryghost/mw-error-handler');
 const APIVersionCompatibilityService = require('../../services/api-version-compatibility');
 
+/**
+ * @returns {import('express').Application}
+ */
 module.exports = function setupApiApp() {
     debug('Parent API setup start');
     const apiApp = express('api');

ghost/core/core/server/web/api/endpoints/admin/app.js

@@ -12,6 +12,9 @@ const routes = require('./routes');
 const APIVersionCompatibilityService = require('../../../../services/api-version-compatibility');
 const GhostNestApp = require('@tryghost/ghost');
 
+/**
+ * @returns {import('express').Application}
+ */
 module.exports = function setupApiApp() {
     debug('Admin API setup start');
     const apiApp = express('admin api');

ghost/core/core/server/web/api/endpoints/admin/middleware.js

@@ -8,6 +8,11 @@ const messages = {
     notImplemented: 'The server does not support the functionality required to fulfill the request.'
 };
 
+/**
+ * @param {import('express').Request} req
+ * @param {import('express').Response} res
+ * @param {import('express').NextFunction} next
+ */
 const notImplemented = function notImplemented(req, res, next) {
     // CASE: user is logged in, allow
     if (!req.api_key) {
@@ -63,8 +68,12 @@ const notImplemented = function notImplemented(req, res, next) {
     }));
 };
 
+/** @typedef {import('express').RequestHandler} RequestHandler */
+
 /**
  * Authentication for private endpoints
+ *
+ * @type {RequestHandler[]}
  */
 module.exports.authAdminApi = [
     auth.authenticate.authenticateAdminApi,
@@ -79,6 +88,8 @@ module.exports.authAdminApi = [
 /**
  * Authentication for private endpoints with token in URL
  * Ex.: For scheduler publish endpoint
+ *
+ * @type {RequestHandler[]}
  */
 module.exports.authAdminApiWithUrl = [
     auth.authenticate.authenticateAdminApiWithUrl,
@@ -92,6 +103,8 @@ module.exports.authAdminApiWithUrl = [
 
 /**
  * Middleware for public admin endpoints
+ *
+ * @type {RequestHandler[]}
  */
 module.exports.publicAdminApi = [
     apiMw.cors,

ghost/core/core/server/web/api/endpoints/admin/routes.js

@@ -7,6 +7,9 @@ const mw = require('./middleware');
 const shared = require('../../../shared');
 const labs = require('../../../../../shared/labs');
 
+/**
+ * @returns {import('express').Router}
+ */
 module.exports = function apiRoutes() {
     const router = express.Router('admin api');
 

ghost/core/core/server/web/api/endpoints/content/app.js

@@ -9,6 +9,9 @@ const routes = require('./routes');
 const errorHandler = require('@tryghost/mw-error-handler');
 const apiVersionCompatibility = require('../../../../services/api-version-compatibility');
 
+/**
+ * @returns {import('express').Application}
+ */
 module.exports = function setupApiApp() {
     debug('Content API setup start');
     const apiApp = express('content api');

ghost/core/core/server/web/api/endpoints/content/middleware.js

@@ -12,6 +12,8 @@ const shared = require('../../../shared');
 
 /**
  * Authentication for public endpoints
+ *
+ * @type {import('express').RequestHandler[]}
  */
 module.exports.authenticatePublic = [
     shared.middleware.brute.contentApiKey,

ghost/core/core/server/web/api/endpoints/content/routes.js

@@ -5,6 +5,9 @@ const {http} = require('@tryghost/api-framework');
 const mw = require('./middleware');
 const config = require('../../../../../shared/config');
 
+/**
+ * @returns {import('express').Router}
+ */
 module.exports = function apiRoutes() {
     const router = express.Router('content api');
 

ghost/core/core/server/web/api/middleware/upload.js

@@ -156,10 +156,16 @@ const checkFileIsValid = (fileData, types, extensions) => {
  *
  * @param {Object} options
  * @param {String} options.type - type of the file
- * @returns {Function}
+ * @returns {import('express').RequestHandler}
  */
 const validation = function ({type}) {
     // if we finish the data/importer logic, we forward the request to the specified importer
+
+    /**
+     * @param {import('express').Request} req
+     * @param {import('express').Response} res
+     * @param {import('express').NextFunction} next
+     */
     return function uploadValidation(req, res, next) {
         const extensions = (config.get('uploads')[type] && config.get('uploads')[type].extensions) || [];
         const contentTypes = (config.get('uploads')[type] && config.get('uploads')[type].contentTypes) || [];
@@ -192,7 +198,7 @@ const validation = function ({type}) {
  *
  * @param {Object} options
  * @param {String} options.type - type of the file
- * @returns {Function}
+ * @returns {import('express').RequestHandler}
  */
 const mediaValidation = function ({type}) {
     return function mediaUploadValidation(req, res, next) {

ghost/core/core/server/web/comments/routes.js

@@ -7,6 +7,9 @@ const shared = require('../shared');
 const bodyParser = require('body-parser');
 const membersService = require('../../../server/services/members');
 
+/**
+ * @returns {import('express').Router}
+ */
 module.exports = function apiRoutes() {
     const router = express.Router('comment api');
     router.use(bodyParser.json({limit: '50mb'}));

ghost/core/core/server/web/members/app.js

@@ -16,6 +16,9 @@ const api = require('../../api').endpoints;
 const commentRouter = require('../comments');
 const announcementRouter = require('../announcement');
 
+/**
+ * @returns {import('express').Application}
+ */
 module.exports = function setupMembersApp() {
     debug('Members App setup start');
     const membersApp = express('members');

ghost/core/core/server/web/parent/app.js

@@ -4,6 +4,9 @@ const express = require('../../../shared/express');
 const compress = require('compression');
 const mw = require('./middleware');
 
+/**
+ * @returns {import('express').Application}
+ */
 module.exports = function setupParentApp() {
     debug('ParentApp setup start');
     const parentApp = express('parent');

ghost/core/core/server/web/parent/backend.js

@@ -4,7 +4,7 @@ const {BASE_API_PATH} = require('../../../shared/url-utils');
 
 /**
  *
- * @returns {import('express').RequestHandler}
+ * @returns {import('express').Application}
  */
 module.exports = () => {
     debug('BackendApp setup start');

ghost/core/core/server/web/parent/frontend.js

@@ -5,7 +5,7 @@ const shared = require('../shared');
 /**
  *
  * @param {import('../../../frontend/services/routing/RouterManager').RouterConfig} routerConfig
- * @returns {import('express').RequestHandler}
+ * @returns {import('express').Application}
  */
 module.exports = (routerConfig) => {
     debug('FrontendApp setup start', routerConfig);

ghost/core/core/server/web/parent/middleware/emit-events.js

@@ -3,6 +3,11 @@ const INVALIDATE_ALL = '/*';
 // Emit the site.changed event, a special model event used for webhooks
 const events = require('../../../lib/common/events');
 
+/**
+ * @param {import('express').Request} req
+ * @param {import('express').Response} res
+ * @param {import('express').NextFunction} next
+ */
 module.exports = function emitEvents(req, res, next) {
     res.on('finish', function triggerEvents() {
         if (res.get('X-Cache-Invalidate') === INVALIDATE_ALL) {

ghost/core/core/server/web/parent/middleware/ghost-locals.js

@@ -1,7 +1,12 @@
 const ghostVersion = require('@tryghost/version');
 
-// ### GhostLocals Middleware
-// Expose the standard locals that every request will need to have available
+/**
+ * Expose the standard locals that every request will need to have available
+ *
+ * @param {import('express').Request} req
+ * @param {import('express').Response} res
+ * @param {import('express').NextFunction} next
+ */
 module.exports = function ghostLocals(req, res, next) {
     // Make sure we have a locals value.
     res.locals = res.locals || {};

ghost/core/core/server/web/parent/middleware/log-request.js

@@ -2,6 +2,10 @@ const logging = require('@tryghost/logging');
 
 /**
  * @TODO: move this middleware to Framework monorepo?
+ *
+ * @param {import('express').Request} req
+ * @param {import('express').Response} res
+ * @param {import('express').NextFunction} next
  */
 module.exports = function logRequest(req, res, next) {
     const startTime = Date.now();

ghost/core/core/server/web/parent/middleware/queue-request.js

@@ -44,6 +44,11 @@ module.exports = function queueRequest(
         debug(`Request completed: ${job.data.req.path}`);
     });
 
+    /**
+     * @param {import('express').Request} req
+     * @param {import('express').Response} res
+     * @param {import('express').NextFunction} next
+     */
     return function queueRequestMw(req, res, next) {
         req.queueDepth = queue.queue.getLength();
 

ghost/core/core/server/web/parent/middleware/request-id.js

@@ -2,6 +2,10 @@ const uuid = require('uuid');
 
 /**
  * @TODO: move this middleware to Framework monorepo?
+ *
+ * @param {import('express').Request} req
+ * @param {import('express').Response} res
+ * @param {import('express').NextFunction} next
  */
 module.exports = function requestIdMw(req, res, next) {
     const requestId = req.get('X-Request-ID') || uuid.v4();

ghost/core/core/server/web/webmentions/routes.js

@@ -5,6 +5,9 @@ const shared = require('../shared');
 
 const bodyParser = require('body-parser');
 
+/**
+ * @returns {import('express').Router}
+ */
 module.exports = function apiRoutes() {
     const router = express.Router('webmentions');
 

ghost/core/core/shared/express.js

@@ -5,6 +5,11 @@ const sentry = require('./sentry');
 
 const lazyLoad = createLazyRouter();
 
+/**
+ *
+ * @param {String} name
+ * @returns {import('express').Application}
+ */
 module.exports = (name) => {
     debug('new app start', name);
     const app = express();