Current and future state of react-docgen

As you may have noticed, I haven’t found the time to keep up with issues and pull requests in the recent months. In this issue I would like to talk about ideas how to handle reac-docgen’s development so that everybody gets the most value out of it.

Features, features, features

Since the initial release of react-docgen, quite a few features have been added:

• Support for class syntax
• Support for stateless functions
• Extracting information about class methods (+ extracting information with jsdoc)
• Support for flow types

and there are currently outstanding ideas such as

• Documenting props in the component docblock (#98)
• Finding all dependencies of a component (#93)

Most of these have been added by external contributors, which is amazing, and I can’t thank you enough for that. I especially wanted to thank @danez, @janicduplessis and @iamdustan for their work.

However, adding these big features also means that the complexity of the core app increases. And since I’m not that familiar with these parts, it’s also more difficult for me to keep with bug reports for them. @danez has created pull requests to improve the flow type logic, but this is not a sustainable model if this still depends on me processing these PRs.

I see two actions we can take to make this better

• Add more maintainers
• Keep the core small / simple

Add more maintainers

This is an easy one: The more people can review issues and PRs, the easier it is to keep things up to date. @wbinnssmith recently joined our team at Facebook and expressed interest in helping out. And of course it only seems reasonable to add @danez, since flow type support is a really big feature.

Keep the core small / simple

From the very beginning react-docgen was designed to be extensible: Handlers contain the actual information extraction logic and it’s possible to write and use your own handlers.

The obvious advantage of this is that it allows developers to customize reac-docgen to their needs. Similar to how coding conventions are subjective and differ from company to company, documentation conventions also differ.

So far I have added new features to the core, but as I said, I don’t think this is sustainable. My suggestion is to keep new features out of the core. If someone wants to make a new feature available to others, they can publish their own npm package (maybe prefixed with react-docgen-…). Of course we would still accept PRs to improve the utility methods to support new features. The other advantage of this is that I / we are not the bottleneck in maintaining these features.

That’s why I think the new suggestions, #93 and #98, should be published as plugins. Maybe we will also move some features that currently are in core outside of (like method documentation).

Overall this would be a similar approach like eslint, except we would still support the basics out of the box. However, I’m also happy to talk about pros and cons of having a monorepo instead, like Babel.

To make plugin creation and usage easier, I think we need to

• Provide a template for handler unit tests.
• Make it easy to add handlers from the command line.

That’s all for now, please let me know what you think!

[ZauberNerd]

Sorry for hijacking this thread. Back to the original topic:

I think it would be good to focus on both options (adding more maintainers and keeping the core small). Just to throw a crazy idea in here: http://openopensource.org/

Adding more maintainers could help:

• reduce the bus factor
• resolve issues and PRs in less time

I like the idea of keeping the core small or even going one step further (like babel) and having this project provide only the infrastructure (resolver and utilities) for other handlers (meaning: taking method, propTypes and displayName handler out of the core). These handlers could still be “core handlers” and be versioned in this repository, but are not automatically included. I think that would help to make the scope clearer on what goes into the core and what stays outside of it.

Cons of that approach could be the overhead of maintaining all these “core handlers” in isolation, maybe even chasing bugs that only occur in special combinations of handlers, confused or overwhelmed users because moving all the handlers out of the core could put more complexity in their projects.

But in any case, I agree that we first need to document and provide examples for how to create and publish custom handlers and figure out a way to make them accessible from the CLI.

[fab1an]

I would be great if one could just augment the default getPropType function and pass it to the handler. That way I could implement my custom props that I need.