[dmpyatyi]

*Clean parameter names, sensible defaults, clear required vs optional. It's basically UX design for machines rather than humans.*

But it's the same points you should follow when designing a human readable docs(as zahlman said above). Isn't it?