In my java apps, I always comment my classes and methods to indicate what they are all about. The problem I often have however is documenting a complete process whereby the process is spread over several classes. I need to document how all the pieces work together to give an easy overview of how something works.
What I find problematic is WHERE I write this documentation. I could just as well write it in a separate file such as a Word document but the documentation tends to become alienated from the actual code and it is possible to get out of sync. On the other hand, if I document it in a single java code file, it makes it difficult for someone reading one of the dependent classes to know how that class fits into the overall process unless they are aware of the documentation in the class where I wrote it. A possible solution is just to include a reference in each class that makes up the entire process and just designate one of the classes as the "primary" class where the documentation originates from.
Or is there a better alternative approach on how I should be doing this?
EDIT:
An example is where you have a mobile app that uploads data to the server and then you download data from the server to another device. You have a process that covers three components (a sending mobile device, the server and the receiving mobile device). None of these can be really considered the "starting point in the overall data transfer process, so when documenting this process, where would this documentation go?
