[syrrim]

APIs should be intuitive; they should be usable only from knowing their signature, and from having familiarity with similar functions. For the most part, DOM/WOM functions are like this, and so the doc will only be repeating things you could have derived intuitively. There are, of course, many situations where the use is non-obvious. In these cases it is even more important to have a good example demonstrating the idiosyncratic usage; a sidenote hidden away in the middle of the doc will easily be missed.