When doing delegation I have a documentation dilemma: do the API docs go in
the delegator or the delegate?
In this case it's Test::Builder2::TestCase which delegates to a stack of
Test::Builder2::EventCoordinator objects. The user will primarily interact
with TestCase objects. Only rarely should they ever touch an EventCoordinator
directly.
Do I put all the documentation in TestCase, because that's what the user will
work with, and put a pointer to EventCoordinator?
This presents a unified interface to the user... but it's harder to maintain.
And if you DO need to use an EventCoordinator it's harder to know which
methods are EC's and which are TestCase's.
Do I document their native methods in their respective classes and point the
TestCase docs at EventCoordinator?
It's inconvenient to the user to have to jump between two class's
documentation to learn how to use one class. But it is easier to maintain.
It also conveys the true nature of things presenting a more accurate model
(not necessarily more useful).
Meanwhile, I'm going with documenting in place. It's easier while the API is
evolving.
Hmmm... sectional POD includes anyone?
--
Look at me talking when there's science to do.
When I look out there it makes me glad I'm not you.
I've experiments to be run.
There is research to be done
On the people who are still alive.
-- Jonathan Coulton, "Still Alive"
