Keeping extension docstrings in sync with the native implementation

In snakeoil, a core rule of our codebase is that extensions must be optional- this is primarily done to make the initial steps of porting pkgcore to a platform easier, and to enable some usages that aren’t extension friendly.

One problem I’ve ran into however is how best to keep your extension docstrings in sync with the native implementations docstrings. I’m not a fan of relying on developers to update docstrings in two places, and I’m not a fan of just storing the documentation on a website or something similar (I generally like my pydoc invocations to be useful, rather than stubs telling me to load a webpage- personal preference however).

Anyone got any suggestions? One thought I’d had was to split the docstrings out into a module the native and extension implementations could import, but that seems a bit too much like a kludge to me- plus it complicates the code a fair bit. The other thought I’d had was to add a set of tests checking extensions vs native, to ensure the two are in sync, but that doesn’t solve the core problem- just make it easier to do the dual maintainence.

So how are others solving this?

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: