microsoft
[api-extractor] classify arrow functions as functions
Is this a feature or a bug?
- [x] Feature
- [ ] Bug
Please describe the actual behavior.
This is a feature request to classify exported arrow functions as functions rather than variables. Even though syntactically the latter is the case, semantically (for documentation & usage purposes) this doesn't make any sense - and worse - it invalidates any documentation effort in the docstrings related to parameter descriptions, return types etc.
The current behavior creates a situation where the doc toolchain implicitly discourages the use of public arrow functions. My entire mono-repo (100+ packages) is largely using arrow functions and as much as I like the API extractor approach, this current behavior is more or less a showstopper. I also can't imagine that this will bite a lot of other projects...
Related, I'd also like to propose that const symbols are not classified as "variable", but at least as "constant"...
If for whatever reason a reclassification of arrow functions as "function" is not possible, then please consider supporting a form of @kind tag to allow manual classification, e.g. @kind function, which then should override the inferred kind.
What is the expected behavior?
Public, exported arrow functions in the form below are extracted & classified as functions, with all that entails.
/**
* Returns true if the first items of `buf` are the same items as in
* `needle`.
*
* @remarks
* This means `buf` should have at least the same length as `needle` for
* this to be true.
*
* By default, uses {@link @thi.ng/equiv#equiv} for equality checking.
*
* {@link endsWith}
*
* @param buf - array to search
* @param needle - search value
* @param equiv - equality predicate
*/
export const startsWith = (
buf: ArrayLike<any>,
needle: ArrayLike<any>,
equiv = _eq
) => {
let i = buf.length;
let j = needle.length;
if (i < j) return false;
while (-j >= 0 && equiv(buf[j], needle[j])) {}
return j < 0;
};
If this is a bug, please provide the tool version, Node.js version, and OS.
- Tool: api-extractor
- Tool Version: 7.5.6
-
Node Version: 12.10.0
- Is this a LTS version? no
- Have you tested on a LTS version? no
- OS: OSX 10.14
This is a good proposal. @postspectacular are you able to help implement it?
@octogonz thank you! i can't say yet if i can help w/ that - just haven't really looked through the source yet. will keep you posted!
FYI there's some general instructions in the Contributing doc.
If you don't have time, let me know. I might be able to help, although I've been pretty busy with https://github.com/microsoft/tsdoc/pull/196 this week since we're trying to roll out eslint-plugin-tsdoc in our repo.
Would the best solution for this be to create a new @kind tag or identify and classify exported arrow functions as functions rather than variables?
I see value in a @kind tag as we have a series of React functional components and it would be nice to categorize them as such and separate from other exported functions.
