I think inline #documentation is an important tool to making software readable. It makes software maintainable, encourages future development and makes it easier to join the project as a developer.
This is why I advocate for #mastodon to start encouraging inline documentation with #yardoc, requiring it for any new PRs and serving this API documentation on joinmastodon.org.
https://github.com/mastodon/mastodon/issues/29141
See: babka