Generate docs for hooks

[rolandjitsu]

Since hooks have been released a while back, it would be nice to be able to generate docs for them.

For example, for a simple hook:

import {useState} from 'react';

/**
 * A hook to do something
 *
 * @param {object} params
 * @param {boolean} [params.disabled] Disable the thing
 * @returns {boolean}
 */
const useMyHook = (params) => {
  const [isUsing, setUsing] = useState(false);
  // Some logic here to invoke setUsing()
  return isUsing;
};

export default useMyHook;

There is not way to generate some docs. Or is there and I just can't find it?

NOTE: I am actually using react-styleguidist which uses this lib to generate component docs.

[fkling]

Since those are just simple functions, you could likely just use jsdoc to generate documentation for them.

Not sure whether this needs to be included in react-docgen itself...

[rolandjitsu]

@fkling I actually tried to use jsdoc-to-markdown, but the generated content does not really align with the content this lib generates.

I'm also not sure if this lib should generate the docs for a hook fn, but it would definitely make some ppl happy if it did.

[behivetech]

Being a user of react styleguidist, it's frustrating I'm going to have to manually doc all the hook components. It looks to me like react is pushing towards going from classes to functions. Shouldn't this library start moving towards that so it doesn't become obsolete. It's such a handy tool and makes documentation very easy! At the very least it would be nice if react-docgen would scrape for prop types regardless of if it's a class or function.

[fkling]

@Bruqui

At the very least it would be nice if react-docgen would scrape for prop types regardless of if it's a class or function.

react-docgen is and has been doing this for a long time. I don't see what this has to do with hooks. Hooks are generally an implementation detail of a component and not part of its public API. Am I missing something?

[behivetech]

Oh... maybe I'm missing something. I'm using react styleguidist. Any of my components that are functions aren't picking up propTypes. All the components that are classes do get the propTypes. What I was meaning is if you use a react hook, you can't use a class for your component. If react-docgen works with functions, maybe I need to get react-docgen to run directly on these and check the JSON to see if it is actually getting the propTypes and there's something wrong with styleguidist. I actually tried that once, but I get this message... "Still waiting for std input..." when I run the command react-docgen -o src/components-core --pretty and nothing happens so I need to figure out what's going on there as well.

[behivetech]

OK... I was screwing up. I was thinking the -o was the path to the files not the file that was output. I misread the docs. Got it working and it looks like styleguidist is the issue, because I DO see the props for the components that are functions from the JSON that was generated. Sorry for the trouble. Oh and thank you for the help. This docgen is pretty awesome!!!

[fkling]

@Bruqui, no worries!

[trevordmiller]

"Hooks are generally an implementation detail of a component and not part of its public API"

I believe this is true for app projects. But for libraries where custom hooks are a part of the public facing interface, this is often not the case in my experience. For example:

• Redux
• Apollo

etc.

Our organization has a good amount of custom hooks like these that are a part of libraries we expose publicly. It would be really nice if these could be auto-documented with react-docgen with the rest of our React code. Although technically "just functions" they are still coupled with React so IMO it makes sense to support them in this library.

I would imagine the most common users are using tools like Storybook or react-styleguidist that use react-docgen under the hood, where auto documentation of their hooks would be helpful.

[dagerikhl]

Adding my support for this, as it's still an open issue.

My use-case is like @trevordmiller describes above: I'm making a component and utility lib, Primors (https://github.com/dagerikhl/primors), and I expose, among other things, hooks as part of the package. I use Storybook to live document my library, as can be seen here: https://dagerikhl.github.io/primors

react-docgen does a wonderful job with components, allowing me to document the components in their own files (thank you <3), but for hooks it doesn't work quite as well. I manually have to enter the description as argTypes for Storybook to render it, as it's unable to parse it from the interface of the hook, see example here: https://github.com/dagerikhl/primors/tree/main/src/hooks/useStateFromProp

Would love for support for generating this for hooks as well as components for these kind of cases.

[danez]

The bigger questions for this is not if we are going to support it, but how. Hooks are just generic functions, so it would be really hard to distinguish hooks from other "normal" functions. The only thing that could work is some react-docgen specific jsdoc annotation. If anyone has better ideas I'm open to hear them.

[dagerikhl]

Valid point.

A JSDoc annotation is an option.

Another option is using the convention that hooks are prefixed by use.... This isn't consistently reliable, but a pretty well established convention and fronted by the React team, so it might be viable.

Would supporting functions as a whole be another option? Perhaps behind a flag to allow people to opt out of the functionality? Not sure what impact this would have on this library.

[guoyunhe]

@danez My thinking about how to distinguish hooks from normal functions:

1. The function name must match /^use[A-Z]/ pattern.
2. The function description must NOT contain _NOT_REACT_HOOK_. This allow users to exclude some useXXX functions.