Make WordPress Core

Opened 3 years ago

Last modified 21 months ago

#52888 reviewing enhancement

Docs: Update get_children function

Reported by: ribaricplusplus's profile ribaricplusplus Owned by: sergeybiryukov's profile SergeyBiryukov
Milestone: Future Release Priority: normal
Severity: minor Version:
Component: Posts, Post Types Keywords: has-patch dev-feedback
Focuses: docs Cc:

Description

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.

Attachments (1)

52888.diff (3.5 KB) - added by ribaricplusplus 3 years ago.

Download all attachments as: .zip

Change History (11)

#1 @mukesh27
3 years ago

  • Keywords has-patch added
  • Summary changed from Fix get_children documentation to Docs: Update get_children function

#2 @SergeyBiryukov
3 years ago

  • Component changed from General to Posts, Post Types
  • Milestone changed from Awaiting Review to 5.8

#3 @SergeyBiryukov
3 years ago

  • Owner set to SergeyBiryukov
  • Status changed from new to reviewing

#4 @desrosj
3 years ago

  • Milestone changed from 5.8 to 5.9

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.

This ticket was mentioned in Slack in #core by audrasjb. View the logs.


3 years ago

This ticket was mentioned in Slack in #core by audrasjb. View the logs.


3 years ago

#7 @hellofromTonya
2 years ago

  • Milestone changed from 5.9 to 6.0

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.

#8 @ribaricplusplus
2 years ago

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.

#9 @costdev
2 years ago

  • Milestone changed from 6.0 to 6.1

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.

#10 @davidbaumwald
21 months ago

  • Keywords dev-feedback added
  • Milestone changed from 6.1 to Future Release

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.

Note: See TracTickets for help on using tickets.