Procedurally generate API documentation from source #1165
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
|
This is great, thanks for picking it up again! |
fb55
added a commit
that referenced
this pull request
Oct 3, 2018
* Use parse5 as a default parser (closes #863) * Use documents via $.load * Add test for #997 * Change options format * Update unit test Update test phrasing according to recent changes in parsing logic. * 1.0.0-rc.1 * Improve release process Limit responsibility of "pre-publish" script to simply validate the project's `History.md` file (by verifying an entry for the current release). Define a separate script for history generation. Separating the workflow in this way allows for manual modification of the release notes. * Correct errors in Readme.md * Document advanced usage with htmlparser2 * Update History.md (and include migration guide) * Remove documentation for `xmlMode` option Simply expose an option named `xml` that enables XML parsing via htmlparser2 with the ability to specify additional options for that parser. * Rename `useHtmlParser2` option This flag is used to control parsing behavior internally, but it is not intended for use by consumers. Prefix the name with an underscore in order to discourage users from relying on it. * Re-write migration guide for version 1.0 (#1078) Incorporate recent feedback from consumers who have experimented with the version 1.0 release candidate. * Pass locationInfo option to parse5 (#1155) * Update css-select to the latest version 🚀 (#1158) Breaking change: Invalid selectors now throw Errors, not SyntaxErrors. * Use eslint & prettier, add precommit hook (#1152) * chore(package): update mocha to version 5.0.4 (#1088) * Ensure text nodes expose the DOM level 1 API Since enabling the `withDomLvl1` parsing option, nodes cannot be created with an object literal. Create new text nodes using the `evaluate` function to ensure they expose the correct attributes. * fixing missing prop(‘outerHTML’) implementation. Added an ‘outerHTML’ case to the switch in the prop function, which wraps a clone of in a container element, and sets to that container's HTML (#945) * Do not lint files excluded from version control (#1162) This includes code coverage reports as generated by the command `make test-cov`. * Correct typo in git hook configuration (#1163) * Correct typo in git hook configuration * Reformat package manifest to satisfy linter * Fix .text with a function as the argument * Fix `.text` being called on a collection with size > 1 with a function * chore(package): update coveralls to version 3.0.0 (#1086) * Update jsdom to the latest version 🚀 (#1008) * Throw a useful error on invalid input to cheerio.load() (#1087) * Procedurally generate API documentation from source (#1165) * Use parse5 to serialize the DOM, use lodash to clone dom * Fix DoS/RCE vulnerability in lodash@4.15.0 (#1179) fixes #1175 * Add eslint-plugin-jsdoc, improve documentation (#1168) * Improve variable names (#1183) Promote consistency in variable names within the project's source and unit tests. This helps to highlight the distinction between the object exported by the module and the function produced by the `load` method. The latter value is expected to mimic the jQuery API, while the former value generally should only be used for a small set of methods specific to Cheerio: - `load` - `html` - `xml` - `text` Other usages of the exported object are discouraged, and a future patch will update the unit tests to reflect the usages that are endorsed for long-term stability. * Formally test deprecated APIs (#1184) Methods named `load`, `html`, `xml`, and `text` are defined in many locations: Today, Cheerio defines multiple versions of methods named `load`, `html`, `xml`, `text`, and `parseHTML`. These alternate versions may be defined in up to three distinct parts of the API: - exported by the Cheerio module - as static methods of the "loaded" Cheerio factory function - as instance methods of the "loaded" Cheerio factory function Some of these are surperfluous, and because some unecessarily conflict with idiomatic jQuery coding patterns, they have been designated for future removal [1]. Add tests for the deprecated methods in order to avoid regressions prior to their removal. Insert comments to delineate the methods which are endorsed and which have been deprecated. For the latter group of methods, include recommendation for the preferred alternatives. [1] #1122 * Implement for...of iterator via Symbol.iterator (#1197) * Implement for...of iterator via Symbol.iterator Similar to jQuery: https://github.com/jquery/jquery/blob/1ea092a54b00aa4d902f4e22ada3854d195d4a18/src/core.js#L371-L373 Fixes #1191 * Assert that the iterator ends #1197 (comment)
fb55
pushed a commit
that referenced
this pull request
Sep 10, 2020
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.
My primary concern with the generated documentation is that it doesn't make a clear distinction between instance methods and static methods. This is a result of a deficiency in the tooling (JSDoc). I've offered to help fix that, but I never received a response.
I think we could work around this informally by documenting the distinction in text as part of the description of the "static" module, but we're still not very rigorous about how we use that term internally--see gh-1122.
@fb55 what do you think about merging this and resolving gh-1122 as a follow-up?