Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

Combine EventCoodinator docs into TestState #172

Closed
schwern opened this Issue · 3 comments

2 participants

@schwern
Owner

TestState delegates to EventCoordinator. Users will be primarily interacting with TestState so it would be nice if they could see the documentation for its complete interface in one place. But it's much easier to write the docs for TestState and EventCoordinator in place.

To get the best of both worlds, we need a tool which can copy the relevant bits of EventCoordinator's docs into TestState's docs. The result would be output as TestState.pod which perldoc will pick up before TestState.pm. The user sees unified docs, EventCoordinator still has docs, and we can write them split.

Write a tool, and if necessary restructure the TestState and EventCoordinator docs, to do this.

Don't worry about integrating it into the build system.

@timgimyee

Will add fake pod like this to TB2::TestState:

=for include TB2::EventCoordinator#Attributes

=for include TB2::EventCoordinator#Methods

Then a script to replace those with the Attributes and Methods sections of TB2::EventCoordinator.

@schwern
Owner

Sounds good. Watch out for duplicates. If TestState already has an EventCoordinator method documented, assume it's been overridden and don't add the EC docs.

@timgimyee

Will look for duplicates in =headN and X<>. So if EventCoordinator has:

=head3 post_event

Then there's a duplicate if TestState has:

=head4 post_event

Or:

=head4 Overridden post_event method
X

@schwern schwern closed this
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.