One of the problems I'm finding in learning how to write directives in angular is the API.  I find it to be way too cryptic, particularly in regards to scope.  
Below is a brainstorm regarding possible improvements(?) to the directive definition api.