[api-extractor] classify arrow functions as functions

[postspectacular]

Is this a feature or a bug?

• 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

[octogonz]

This is a good proposal. @postspectacular are you able to help implement it?

[postspectacular]

@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!

[octogonz]

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 microsoft/tsdoc#196 this week since we're trying to roll out eslint-plugin-tsdoc in our repo.

[JamesBurnside]

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.

[cary-hu]

+1 for this issue

any update for arrow function parameter?

[EveChee]

Hi,where are we on this issue so far？

[octogonz]

We need a volunteer to implement it

[bartvandenende-wm]

this should be resolved in @microsoft/api-extractor v7.40.0