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

Documentation: errors aren't reported when API docs can't be generated #15680

Closed
oandregal opened this issue May 16, 2019 · 1 comment
Closed

Documentation: errors aren't reported when API docs can't be generated #15680

oandregal opened this issue May 16, 2019 · 1 comment
Assignees
@oandregal
Labels
[Type] Bug An existing feature does not function as intended [Type] Developer Documentation Documentation for developers

Comments

@oandregal
Copy link
Member

We use ./bin/update-readme to update the API docs for many packages. When there is an error for one of the packages it isn't reported by the script and changes in the public API aren't reflected in the README.

At the moment, this is happening for block-editor and edit-post packages.
@oandregal oandregal added [Type] Bug An existing feature does not function as intended [Type] Developer Documentation Documentation for developers labels May 16, 2019
@oandregal oandregal self-assigned this May 16, 2019
@oandregal oandregal changed the title Errors aren't reported for READMEs that fail to update Documentation: errors aren't reported when API docs can't be generated May 16, 2019
@oandregal oandregal mentioned this issue May 16, 2019
Merged
@oandregal
Copy link
Member Author

Closed by #15679

oandregal pushed a commit that referenced this issue May 16, 2019
@nosolosw
Fixes update-readme script (#15679)
ed630e8 
This PR does two things:

- Fixes #15626 and #15680 by making the script synchronous. In #15200 we missed the fact that to fill tokens within the same file we need to execute docgen synchronously, otherwise, the last token process will overwrite the first.

- Updates our espree dependency to 4.0.0. When error reporting was back, we uncovered that introducing short Fragment syntax in #15120 caused docgen to fail. The reason is that the espree version we used didn't support that. This fixes it by upgrading it to one that does. A couple of restrictions:

    - espree uses acorn-jsx to power JSX parsing.
    - acorn-jsx@4.1.0 added support for JSX fragment short syntax (patched in 4.1.1).
    - espree@4.0.0 added acorn-jsx@4.1.1. We should use this at a minimum.
    - espree@4.1.0 added acorn@6 and acorn-jsx@5 for parsing. This caused an error I couldn't identify the source.
    - espree@5.0.0 removed support for the attachComment. We use this for collocating the JSDoc comment with the proper export statement. Without this, we can't migrate to espree@5.0.0.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@oandregal oandregal

Labels
[Type] Bug An existing feature does not function as intended [Type] Developer Documentation Documentation for developers
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
1 participant
@oandregal