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.
@serge many of the projects we use in Python, like #Flask, are documented using #Sphinx, which can be configured to automatically generate API documentation from Python source code:
This is (similar to the #yardoc and #rdoc situation) backwards compatible with #pydoc, though much more expressive due to the machine-readable format for defining parameters, return values and potential exceptions:
After a few arduous months of getting the JokeBot #framework off the ground, I have finally got the framework core polished and ready for wider adoption. The #mastodon adapter will enter its release candidate phase and become stable (hopefully) later today, and the #misskey adapter will enter development afterwards.
With @JokeBot up and running, I have the docs mostly ready to use, except there are a few broken links that lead to 404s as well as some a11y issues. I'm fixing to get in contact with the #yardoc team to troubleshoot the issues, but they probably won't be fixed any time soon, so I didn't see the point for pushing back the release until those issues are resolved. Other than that, I'm glad that I'm making progress! 🥳