Feature/525 return findings for ContainElement

[thediveo]

implements RFC #525:

• implements an optionalPointer parameter to ContainElement for returning matching contained element(s)
• adds unit tests related to returning matching contained elements
• updates documentation for ContainElement

[thediveo]

One note: the diff for the unit tests look ugly, but that's an unfortunate flaw of beloved diff. I've checked again and what I did was to wrap the existing tests for ContainElement in a Describe for the non-result-returning cases and then added separate new unit tests that cover the cases of returning macthed contained elements. More tests on the correct and useful error handling when the optional return pointer points at something that doesn't fit in with the type of actual.

[onsi]

gah sorry again for the delay. I love this - it's gonna be super handy :)

[onsi]

hey @thediveo how would you feel about becoming a collaborator with commit rights? you're contributions have been super valuable and thoughtful!

No expectations on my end to do any maintenance/issues/PRs or anything like that (though if you're interested I won't say no 😉) - and I'm always happy to work on RFCs/PRs with you - but I don't want to be a blocker when my schedule is constrained.

[thediveo]

Hi @onsi I don't mind about the delays, they're part of our lives. I feel very honored by your offer and gladly accept, albeit I still want PR feedback and discussions, except for maybe some minor type fix in the documentation as I happen to come across them.

[onsi]

🎉 sounds great! will add you now 😊