I use most code from OS projects and I've always preferred good use examples. I see a lot of overly simple use examples which really give no direction for a new

I use most code from OS projects and I've always preferred good use examples. I see a lot of overly simple use examples which really give no direction for a new user(Apple ios examples). Any format works but list all the methods of a class. And list what arguments they accept and the acceptable types of each. And finally list what is returned. I document my code as a business logic statement. Eg given credit card, process payment. I then write the validations in a way that reads simple and thus is documentation. If it's a complex line that takes more that a few seconds to parse mentally. I will write out what it does. That's pretty rare. Non programmers never see my code so that works just fine.