> The page for directives is another (in)famous part of the docs that, despite relating to one of the most important aspects of the framework, is often derided as being overly dry
While that used to be true, the directives page recently got updated to provide a much better and simple guide to directives along with plently of code samples -
http://docs.angularjs.org/guide/directive
There is still some work to do. Read the paragraph about transclude : true? $transclude is one of the best features of advanced directives, and the paragraph is still the old one which leaves you with a "... what?" even after you read it 5 times. An example is very much in roder here, but how long should the article be? Before, this section was actually in the guide, and the doc for $compile was neat and clear. Now it's actually messier than before.
While that used to be true, the directives page recently got updated to provide a much better and simple guide to directives along with plently of code samples - http://docs.angularjs.org/guide/directive