Write documentation

[ozankaymak]

Proposal Description

For both easier onboarding of new people and better DX, we need to write more documentation.

[mmtftr]

I believe we can approach this systematically. Using Rustdoc is the industry standard for documenting a crate, so I believe we can start from there. We can use this as a tracker issue to track work on documenting the codebase.

A couple of candidate tasks for the first stage:

• Auto-generated and hosted rustdoc (this looks like a good starting point)
• README improvements like:
  • including an overview of the bridge, linking to important documents and concepts (BitVM bridge, MuSig2, P2TR, classical transactions, bitcoin contracts etc.)

[mmtftr]

• Another great thing would be to have a CONTRIBUTING.md that both introduces the project on an overview-level and provides guidance on how to contribute (our testing, documentation, coverage standards, PR contents, commit formatting, preferred PR merge, branch naming convention, branch explanations [dev vs main etc] etc.).
• On a similar note, it'd be great if we adopt Doctesting, especially for simpler functions where the documentation could provide sufficient tests. A lot of unit tests could probably be rolled into doctests. Of course, some functions are way too complicated to test within doctests.

[ceyhunsen]

• I think it will be more appropriate to keep concepts in other documentations, outside of Clementine, like Clementine onboarding docs
  • Or in a separate dir called docs/
  • Readme can just include small intro to Clementine and how to run it
• Add CONTRIBUTING.md #364 contributing.md
• I believe we can slowly shift basic unit tests to doctests and add rustdoc support
  • It should be very good if we adopt it but there is no rush to do that rn
  • Everyone slowly switching to this will help having this habit for everyone of us, rather than single person doing all the work
  • I suggest we should push ourselves to do this in our PR's for the new codes
  • It will be nice to move basic unit tests to doctest, if one's PR touches that specific part of code or in the same context

[ozankaymak]

Can you update/open issues related to this issue? @ceyhunsen @mmtftr