API Documentation
In life we are free to define the same thing in many ways. I recently of read two separate definitions for Routed Events and presumably written by the same author. It his / her preface the author remarked that you could define Routed Events in two ways, a functional definition and an implementation definition. I cant imagine a world where the implementation definition is really that useful can you? Here they are:
Functional definition: A routed event is a type of event that can invoke handlers on multiple listeners in an element tree, rather than just on the object that raised the event.
Implementation definition: A routed event is a CLR event that is backed by an instance of the RoutedEvent class and is processed by the Windows Presentation Foundation (WPF) event system.
I read the functional definition and I say to myself, wow that’s cool, I can see myself using that…..very useful…..etc, etc. I read the implementation definition and begin to think it’s time for a coffee and a cookie. I have put together quite a few NDoc, SandCastle, JavaDoc API library and help documents over the years and when I strike one myself that exclusively uses “Implementation” definitions like the one discussed here, my head wants’ to explode. So please, do your colleagues a favour, if your going to document things, then only include implementation definitions if you have a functional one to go with it. In the case of API styled documents such as those produced by tools such as NDoc and SandCastle, often it’s the API signatures and examples that adequately describe the implementation definition at any rate.
