Personally, I like maps. So I would probably start with an Entity Relationship Diagram. After that, I would probably do some kind of interaction diagram.
I have been at that place before, it does help to have a map just to keep straight in my brain where in the code I am. | [reply] |
I would still document each class seperately, pointing out when it takes instances of your other classes as parameters - eg "this method takes named parameters. The 'bar' parameter is required, and must be a Bar object, the 'baz' parameteris optional ...". Document what the method does, including how it interacts with the objects passed to it. However, if any of those objects in turn do stuff to other objects, that is properly documented in their docs, not in the ones for the original class.
As for documenting inheritance, that's pretty simple. Something like this, perhaps:
=head1 INHERITANCE
This module inherits methods from Foo and Bar
=head1 METHODS
The following methods override methods in Foo:
...
The following methods override methods in Bar:
...
The following methods are additionally defined:
...
If you end up inheriting the same method name from two seperate base classes, then I suggest that you provide your own implementation which explicitly calls the correct base method, and you should also document that prominently.
So you will end up with a bunch of docs explaining what each method of each class does and how those methods interact with the outside world. From that, you can write your tests and it will probably now be a lot clearer to you what all the interactions are. Then some documentation covering very briefly what each class does and what it represents, and what their interdependencies are should be quite easy to write. You might be able to draw a diagram for that if it's reasonable simple - and if you can, do so, as pictures convey an awful lot more information than words in this situation. I believe there are automated tools for doing this, such as Autodia, although I don't use such things myself, preferring to grovel over the docs and draw on real paper with a real pencil ;-) | [reply]
[d/l] |