Docs: Update get_children function

[ribaricplusplus]

get_children documentation is very confusing to read, an entire essay for what could be said in a single paragraph, so I've rewritten it.

[desrosj]

This is a documentation only change, which can be included during the beta part of the release cycle. But I'd like to understand why this description is so long, and if there are any historical reasons for any of the callouts in this docblock. I'm punting to 5.9, but if someone is able to tackle this during 5.8 beta, it can be moved back.

[hellofromTonya]

While the docblock is long, if it provides context and better understanding, then it's worth having it remain in place. That said, I agree with @desrosj, an exploration is needed to first understand if there are historical reasons and if the context does actually lean into better understanding.

With 5.9 RC1 tomorrow and no movement on this ticket since 5.8, moving it to 6.0.

[ribaricplusplus]

In my opinion, the longer documentation does not provide better understanding. Wouldn't have rewritten it otherwise. For example, the entire discussion about "we could make attachments the child of a post but nah this is no longer accurate" is irrelevant and just confuses anyone who reads this.

[costdev]

While this is a documentation-focused ticket, it is quite a large change from the original documentation.

The discussion about whether this change should be made is still being discussed, so I'm going to move this to the 6.1 milestone for now.

If anyone feels that this ticket has moved towards being committed before 6.0 RC1, feel free to bring it back into the milestone for commit consideration.

[davidbaumwald]

With 6.1 Beta 1 releasing tomorrow and this ticket still needing discussion and a decision about whether to actually update this docblock, this is being moved to Future Release.

If any maintainer/committer wishes to assume ownership of this during a specific cycle, feel free to update the milestone at that time.

Trac ticket: #52888

[sainathpoojary]

Refreshed patch to apply cleanly against the latest trunk.