Discussion: How to document objects/interfaces in function arguments

I’m currently trying to add TSDoc comments to a custom React hook that I’d like to release on npm. The only argument passed to the function is an optional config object which I’m destructuring. I can add a summary to the function fine, which works with IntelliSense, but when trying to document the properties of the config object I’m running into issues. I can’t see the description when I mouseover them.

I can’t see anything in the docs or online about doing this apart from this stackoverflow answer for JSdoc, which doesn’t seem to work.

Below is my function signature. Paste it into the TSDoc playground to see what I mean. I’ve tried abstracting the object types to a separate interface with their own TSDoc comments, as well as using inline TSDoc comments above each line, and they still don’t work.

I’d like users of my package to be able to see the descriptions of the config’s properties as they type or mouseover them. What is the proper way to do this? This is a problem for any functions that have object parameters including React components

/**
 * A custom hook to use `requestAnimationFrame` inside a React component
 *
 * @param config - An optional configuration object for the hook
 * @param config.onStart - A callback that will be run once when the animation starts
 * @param config.onFrame - A callback that will be run on every frame of the animation
 * @param config.onEnd - A callback that will be run on once when the animation ends
 * @param config.delay - A delay in ms after which the animation will start
 * @param config.endAfter - A time in ms after which the animation will be stopped
 * @param config.fps - The desired fps that the animation will be throttled to
 *
 * @returns An object containing the current elapsedTime, frameCount and fps of the animation, as well as a function to stop the animation
 */
const useAnimationFrame = ({
    onStart,
    onFrame,
    onEnd,
    delay,
    endAfter,
    fps: throttledFps
}: {
    onStart?: () => void;
    onFrame?: () => void;
    onEnd?: () => void;
    delay?: number;
    endAfter?: number;
    fps?: number;
} = {}) => {
    let elapsedTime, frameCount, fps, endAnimation;

    // Do stuff

    return { elapsedTime, frameCount, fps, endAnimation };
};

[neefrehman]

@octogonz Thanks for the insight! You’re right, without destructuring the docs are picked up correctly by VSCode.

width and height are part of the Canvas2DDrawProps interface, which contains a bunch of other QoL variables and callbacks that can be passed down for drawing to the canvas. My current version to test on my own projects is here. Its the first library I’m hoping to release, so your notes on simple patterns are useful.

[octogonz]

@neefrehman Without seeing a full code sample, I’m guessing that { width, height } in this expression is not actually typed as Canvas2DDrawProps. You seem to be relying heavily on type inference, so there may be some type algebra reason why the analyzer cannot safely apply the docs to width. (Or maybe it just isn’t smart enough and will get improved in some future compiler release?)

I can repro something similar with this code sample:

interface IOptions {
    /** The width */
    width: number;
    /** The height */
    height: number;
}

type DistanceFunction = (options: IOptions) => number;

const getDistance: DistanceFunction = ({width, height}) => {
    return width + height;
};

I was able to fix it by eliminating the destructuring parameter:

const getDistance: DistanceFunction = (options) => {
    return options.width + options.height;
};

If you are targeting ES5 for web browsers, the transpiled output will look like this. It feels old fashioned to say this, but life often is easier if we avoid fancy syntaxes and write code using simple, explicit patterns. This philosophy applies especially to public APIs that need to be documented and consumed by an unfamiliar audience.