Documentation for native code

[sidorchukandrew]

Thinking about the new initiative around stable core, as well as a recent upgrade from RN74 to 79, has got me thinking: it would be incredible if there was a documentation site for the native side of React Native.

React Native has a number of awesome utilities (like converting DIP to PX and vice versa). But there's no way to know about any of this unless you look at other libraries' native code or the source code of RN itself.

Along that line, many of the packages I needed to update between 74 to 79 were just because certain classes that a turbo module was extending from was deprecated or removed. Native modules provided by RN often inherit from different classes than the RN docs site say to use, which I think I've seen change even between versions.

An official docs site for RN Android and iOS would benefit library authors in 3 ways:

1. Discover the awesome utilities you have already developed
2. Outline which classes should be used and which shouldn't
3. Deepen community understanding of the behind the scenes of RN

Thank you all for your hard work!

[coolsoftwaretyler]

This is something I'm personally very interested in. I spend some time reading React Native source code, PRs, issue threads, etc. But I feel like we would all be better community members and contributors if there was a clearer entry point to learn about these things.

[mateoguzmana]

I created a basic prototype a few months ago for the React Native Android documentation using Dokka. I think it would be great to have something like this integrated directly into the core, so documentation can be autogenerated based on the code itself.

You can check it out here: https://mateoguzmana.github.io/react-native/ (I haven't updated it in a while sadly)

[cortinico]

and might provide documentation for internals we shouldn't rely on.

We can have Dokka to publish only docs for public classes.

What would it look like for the community to start this? Ideally we'd have a list (even a subset) of APIs the RN team has green-lit for common use.

We can just have a repo inside http://github.com/react-native-community that runs on every commit of facebook/react-native, generates the Dokka, and hosts it on GitHub pages

[sidorchukandrew]

If you're asking for more extensive docs related to our native APIs

Is this part something that you'd still want the RN team to handle (at some later point) or also community driven?

[cortinico]

Obviously community maintained docs are more than welcome and we're not against that, but the risk is that any human written docs will get stale really quickly

[sidorchukandrew]

What does a more extensive doc mean compared to something auto-generated? What additional information would get captured and presented to readers?

[cortinico]

For example, looking at this class: https://github.com/facebook/react-native/blob/main/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/ReactHost.kt

Dokka will render the comments in a web page. A more in-depth page will explain what is ReactHost, clarify its lifecycle, perhaps with diagrams, and explains common pitfals, etc. + will link to other relevant classes that might be needed when dealing with ReactHost (e.g. explaining the differences between ReactHost and ReactNativeHost)