Clean up PipeOp documentation

[mb706]

the documentation of @methods is a bit unclean.

split this up: should still only be one "Methods" section, but have some non-bulletpoint text saying to implement a pipeop, the following internal private methods need to be implemented, followed by bullet point list describing private methods in the usual way.

Don't duplicate too much wiht internals, but some duplication is okay.