Opened 7 years ago
Closed 4 years ago
#44411 closed enhancement (fixed)
Add property doc in child class
Reported by: |
|
Owned by: |
|
---|---|---|---|
Milestone: | 5.7 | Priority: | normal |
Severity: | normal | Version: | |
Component: | Customize | Keywords: | |
Focuses: | docs, coding-standards | Cc: |
Description
There are few classes where doc comments are missing for public property declaration.
Examples:
<?php class WP_Customize_Image_Control extends WP_Customize_Upload_Control { public $type = 'image'; public $mime_type = 'image'; ... }
The above class extends WP_Customize_Upload_Control
:
<?php class WP_Customize_Upload_Control extends WP_Customize_Media_Control { public $type = 'upload'; public $mime_type = ''; public $button_labels = array(); public $removed = ''; // unused public $context; // unused public $extensions = array(); // unused ... }
Although the properties are documented in WP_Customize_Media_Control
, it would be good to have them documented inside the scope of each class also. Otherwise one has to navigate to the class which it extends to read the actual documentation. Some cases like the one above could have a multi-level navigation.
Is this worth doing for the sake of better code readability?
Related #44410
Attachments (2)
Change History (6)
#2
@
4 years ago
- Component changed from General to Customize
- Focuses docs added
- Keywords 2nd-opinion removed
- Milestone changed from Awaiting Review to 5.7
- Owner set to SergeyBiryukov
- Status changed from new to reviewing
Hi there, thanks for the patches!
Some history on the @since
tags here:
- These properties were introduced in [20319] / #19910, the version should be 3.4.0:
WP_Customize_Upload_Control::$type
WP_Customize_Image_Control::$type
- These were introduced in [30309] / #21483, the version should be 4.1.0:
WP_Customize_Upload_Control::$mime_type
WP_Customize_Upload_Control::$button_labels
WP_Customize_Image_Control::$mime_type
WP_Customize_Media_Control
was introduced later in [31698] / #29215, that's why its properties are marked as@since 4.2.0
, see [32023] / #31888.
Note: See
TracTickets for help on using
tickets.
Proposed patch for class-wp-customize-image-control.php