Helper documentation/restructure POC #811
Conversation
There was a problem hiding this comment.
Great job on this!
I really like the new JSDocs and the description sentences structure.
Separating each function to its own file and then grouping similar helpers to folders seems like a good approach.
We could just move those things to their own file as well -- worse case it's an extra file, best case maybe that file itself can be used elsewhere as well
I agree with that.
| * @param attributeNames - An array of attribute names to find on the node. | ||
| * @returns An object containing key:value pairs of the attribute names and either their found JSXAttribute object or undefined. | ||
| */ | ||
| export function getSpecifiedAttributes( |
| * @param node - The node to check for any import specifiers. | ||
| * @param imports - A single import specifier or an array of specifiers to find within the import declaration. | ||
| * @param packageName - The package name to check against the import declaration source. | ||
| * @returns A boolean depending on whether the import declaration source matches the packageName, or whether at least 1 import specifier is found. |
There was a problem hiding this comment.
Maybe I'd rewrite this to A boolean depending on whether the import declaration source matches the packageName and at least 1 import specifier is found. So it doesn't sound like it can return true if only the packageName matches. (but maybe it is just my Czech->English language barrier and it makes sense)
| /** | ||
| * Use inline in a test file to push a test object to an invalid test array. | ||
| * @param code The invalid code snippet that should trigger an error. | ||
| * @param output The code snippet that should be output upon the fixer being ran. If no fixer exists, this shoujld be the same as the code parameter. |
There was a problem hiding this comment.
nit: typo
| * @param output The code snippet that should be output upon the fixer being ran. If no fixer exists, this shoujld be the same as the code parameter. | |
| * @param output The code snippet that should be output upon the fixer being ran. If no fixer exists, this should be the same as the code parameter. |
Towards #722 and #725.
For the documentation, we can build upon jsdocs basically. The main thing is the description of the helper function: it should include where it is typically called (inline, at the top of a specific block, as a reference to the create method, etc), and the typical use case ("paired with other logic to conditionally do X or Y").
For the restructuring, I went with the intent of separating things out into their own files as much as possible, then from there creating directories for things that belong together. In this draft for example, the testHelpers file is split into 3 separate files with each housed in a testHelpers directory (the JSXAttributes file would be split out similarly, I only added some documentation there for now). The
getImportPathhelper, though, may not really fit in with any other helpers and would remain in the mainhelpersdirectory (arguably anything that does something or "gets" something from an import specifier/declaration could be grouped together).One question could be what we want to do with things that may not be used elsewhere, e.g. the checkMatchingImportDeclaration helper has a
checkSpecifierExistsfunction that's only used for that helper. We could just move those things to their own file as well -- worse case it's an extra file, best case maybe that file itself can be used elsewhere as well. I don't have a strong opinion either way.This PR also includes some tweaks I had made when I was originally working on a new modal codemod - namely the new getCodeModDataComment helper and some tweaks to the checkMatchingImportDeclaration helper.