fix: jsdoc promise returns #4539
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Resolves an issue in jsdocs for the addressBookContainer that was causing our jsdoc generator to fail with a non-zero exit code. When returning a Promise, we should document it with a ``` @returns {Promise<Type>} Description ``` Generally we've been doing this or just `@returns {Promise} description` If the return block of the jsdoc has the following format it causes errors. ``` @returns {<Promise>Type} Description ```
machikoyasuda
approved these changes
Aug 13, 2018
Merged
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Resolves: issue where master CI builds are failing due to docs existing with non-zero code
Impact: major
Type: docs
Issue
The issue is that in some places in our codebase, we had jsdoc that looked like this:
The
jsdocparser cannot handle the{curly brace followed by<angle bracket and fails to process that line which causes a non-zero exit code. This results in the badge showing a failed CI on our master branch README which is highly undesirable and the reason for this ticket to be marked as impact majorSolution
The solution appears to be using the angle brackets around the type that the Promise resolves to.
This solution was arrived at by consulting the docs http://usejsdoc.org/tags-returns.html and this jsdoc issue comment jsdoc/jsdoc#1197 (comment)
According to this StackOverflow answer, we could potentially go further and define reject types like
{Promise<Object|Error>}, but I can't find specific documentation supporting that behavior yet.https://stackoverflow.com/questions/13104411/how-to-specify-resolution-and-rejection-type-of-the-promise-in-jsdoc
Testing