WordPress.org

Make WordPress Core

Opened 3 years ago

Closed 6 months ago

#44411 closed enhancement (fixed)

Add property doc in child class

Reported by: subrataemfluence Owned by: SergeyBiryukov
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)

44411.class-wp-customize-image-control.diff (637 bytes) - added by subrataemfluence 3 years ago.
Proposed patch for class-wp-customize-image-control.php
44411.class-wp-customize-upload-control.diff (921 bytes) - added by subrataemfluence 3 years ago.
Proposed patch for class-wp-customize-upload-control.php

Download all attachments as: .zip

Change History (6)

@subrataemfluence
3 years ago

Proposed patch for class-wp-customize-image-control.php

@subrataemfluence
3 years ago

Proposed patch for class-wp-customize-upload-control.php

#1 @pento
2 years ago

  • Version trunk deleted

#2 @SergeyBiryukov
6 months 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.

#3 @SergeyBiryukov
6 months ago

In 49679:

Docs: Add documentation for the $type, $mime_type, and $button_labels properties in WP_Customize_Upload_Control.

Follow-up to [20319], [30309], [31698], [32023].

Props subrataemfluence.
See #44411.

#4 @SergeyBiryukov
6 months ago

  • Resolution set to fixed
  • Status changed from reviewing to closed

In 49680:

Docs: Add documentation for the $type and $mime_type properties in WP_Customize_Image_Control.

Follow-up to [20319], [30309], [31698], [32023], [49679].

Props subrataemfluence.
Fixes #44411.

Note: See TracTickets for help on using tickets.