Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

minor jsdoc fixes #4855

Merged
merged 3 commits into from
Jun 30, 2023
Merged

minor jsdoc fixes #4855

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4a76a61
minor jsdoc fixes
Uzlopak Jun 26, 2023
98141e0
Update lib/schema-controller.js
Uzlopak Jun 26, 2023
9802f56
Update lib/schema-controller.js
Uzlopak Jun 26, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
2 changes: 1 addition & 1 deletion lib/reply.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -859,7 +859,7 @@ function notFound (reply) {
* @param {object} context the request context
* @param {object} data the JSON payload to serialize
* @param {number} statusCode the http status code
* @param {string} contentType the reply content type
* @param {string} [contentType] the reply content type
* @returns {string} the serialized payload
*/
function serialize (context, data, statusCode, contentType) {
Expand Down
12 changes: 6 additions & 6 deletions lib/schema-controller.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -100,28 +100,28 @@ class SchemaController {
/**
* This method will be called when a validator must be setup.
* Do not setup the compiler more than once
* @param {object} serverOptions: the fastify server option
* @param {object} serverOptions the fastify server options
*/
setupValidator (serverOption) {
setupValidator (serverOptions) {
const isReady = this.validatorCompiler !== undefined && !this.addedSchemas
if (isReady) {
return
}
this.validatorCompiler = this.getValidatorBuilder()(this.schemaBucket.getSchemas(), serverOption.ajv)
this.validatorCompiler = this.getValidatorBuilder()(this.schemaBucket.getSchemas(), serverOptions.ajv)
}

/**
* This method will be called when a serializer must be setup.
* Do not setup the compiler more than once
* @param {object} serverOptions: the fastify server option
* @param {object} serverOptions the fastify server options
*/
setupSerializer (serverOption) {
setupSerializer (serverOptions) {
const isReady = this.serializerCompiler !== undefined && !this.addedSchemas
if (isReady) {
return
}

this.serializerCompiler = this.getSerializerBuilder()(this.schemaBucket.getSchemas(), serverOption.serializerOpts)
this.serializerCompiler = this.getSerializerBuilder()(this.schemaBucket.getSchemas(), serverOptions.serializerOpts)
}
}

Expand Down
4 changes: 2 additions & 2 deletions lib/schemas.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -147,8 +147,8 @@ function getSchemaAnyway (schema, jsonShorthand) {
*
* @param {object} context the request context
* @param {number} statusCode the http status code
* @param {string} contentType the reply content type
* @returns {function|boolean} the right JSON Schema function to serialize
* @param {string} [contentType] the reply content type
* @returns {function|false} the right JSON Schema function to serialize
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@returns {function|boolean} is correct. The expected value should be documented in the text.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

{function|false} is actuallY correct, as we dont return true but the truthy value of function. This resulted in the place were we call this function that typescript jsdoc typing system threw a typing error, because it said that the result is potentially true and that is not a function.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The proposed change is not valid jsdoc. The return "type" should be an actual type, not an instance of one.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The proposed change is not valid jsdoc.

Depends on which definition of jsdoc that you go by, it is valid in a TS oriented jsdoc parser

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I reference the spec defined at https://jsdoc.app/

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would say that they are different dialects of the same thing, and that one has not had a substantial update in almost 6 years: https://github.com/jsdoc/jsdoc.github.io/commits/master

Where as the TS dialect of it has: https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html

It all depends on where one aims for the JSDoc to be used – if its TS/VSCode, then follow that dialect, if its eg. a documentation generator, then follow whatever dialect it supports.

* the reply or false if it is not set
*/
function getSchemaSerializer (context, statusCode, contentType) {
Expand Down