New documentation

[acdlite]

Using this is as a mega-issue thread to keep track of our documentation efforts.

Recompose's documentation sucks. All we have is a big Markdown file that describes the API, and a README that is little changed from when I originally wrote it, months ago, in a hurry before publishing to npm.

We need to move the API documentation inline so it's easier to maintain, and we need more documents about the purpose, philosophy, and design of the library.

I propose the following steps:

• Use ESDoc to document the API and generate a doc site. documentationjs was also considered, but I really like the user experience of ESDoc sites. As an example, check out the new docs for RxJS.
• Rewrite the README/Introduction to better position the library as, first and foremost, a functional utility library for React components — not a state management library, or a full replacement for class components, or an entire application architecture.
• Doc which discusses components versus higher-order components versus higher-order components with additional arguments (which we've been calling "helpers" but a better name is welcome).
• Doc on performance, perhaps with a section about component squashing.
• Doc on best practices and pitfalls (how not to use the library). This doc should discuss the preferred pattern of composing multiple higher-order components into an enhance HOC, then applying that to the base component.

I'll update this list with links to separate issues as they are created.

[acdlite]

I will start by getting an initial version of an ESDoc site set-up.

@frodosamoa has kindly volunteered to help out. Once I get ESDoc configured, could you go through and add types to the rest of the API?

Anyone who wants to take a stab at any of the other tasks, please add a comment to this issue.

[khanghoang]

Let me know how I can help you guys. I use this package and want to contribute back to it 😁

[pricetula]

Examples or demos would also be great :)

[wuct]

@khanghoang Sorry for late replying. Yes, PRs are always welcome!

[h13i32maru]

Hi! I am developing ESDoc.
https://try.esdoc.org/ (aka REPL) may help you.

Thanks.

[barbalex]

Please add examples.

For instance: It is taking me far too long to grasp how to actually write withProps() correctly.

[threehams]

Working on examples and expanding documentation.

From defaultProps:

Although it has a similar effect, using the defaultProps() HoC is not the same as setting the static defaultProps property directly on the component.

Are there any specific gotchas with this? It's a true sentence, but in its current form it states that it's different without explaining how it's different—or why someone should care.

[istarkov]

@threehams it will not affect your component somehow as it is defaultProps of a HOC.
So you are free to reuse your raw component being sure that no other module polluted it

[threehams]

Is there a general structure in mind for the wiki? I'm fine with the example PR being closed, but everyone still goes to the API docs link right now, and the wiki is a blank page.

[arecvlohe]

I would like to add examples. I have used this library quite a bit so I think that's the least I can do.

[arecvlohe]

Anyone making progress on this issue. Any way I can help?

[wuct]

@arecvlohe I don't think there is someone working on this issue currently. PRs are still welcome :)

[arecvlohe]

@wuct Yeah, I was wondering if progress has been made on getting ESDoc setup. If not, that would be something I could try and tackle to get the ball moving.

[codinglawyer]

Hey everyone,
I've been using Recompose library for some time now and I absolutely love its functional approach. So, I would like to help with the new docs. Just wanted to ask what progress has already been made and which part of the docs can I start to work on. Thanks!

[wuct]

Maybe @arecvlohe is working on ESDoc.

[Stuey2]

Just a note on documentation...

The doc here should probably be deleted: performance

I believe even Andrew's talk about pending performance work is more recent: Recomposing your React application at react-europe 2016

Keep up the good work!

[pokorson]

@arecvlohe @codinglawyer any progress on documentation update? :D maybe we can join our efforts?

[arecvlohe]

I have not made any efforts into starting the ESDoc. I have not used it in the past but if I get it standing I will let you know. Otherwise create a branch start to work on it yourself.

[pokorson]

@arecvlohe I will

[pokorson]

@acdlite is there any branch with documentation in progress or should I just start from scratch?

[wuct]

@pokorson No, there is no branch for new doc currently.