Lack of examples is the major problem, since it is hard to maintain examples in sync with the code. I created tool https://npmjs.org/package/xplain https://npmj

Lack of examples is the major problem, since it is hard to maintain examples in sync with the code. I created tool https://npmjs.org/package/xplain https://npmjs.org/package/xplain that transforms unit tests (javascript) into human readable examples in the API docs. Makes lots of up-to-date examples in the docs possible without any penalty.