Add docblocks to constants (#4441)

* docs: document constants

* chore: document constant in esp integration

* chore: lint

Author: leogermani

includes/author-filter/class-author-filter.php

@@ -132,6 +132,17 @@ private static function get_options_from_users( $capability ) {
 	}
 }
 
+/**
+ * Disables the author filter feature which provides enhanced
+ * author filtering and search capabilities in the admin.
+ *
+ * @constant NEWSPACK_DISABLE_AUTHORS_FILTER
+ * @type     bool
+ * @default  Authors filter enabled
+ * @status   draft
+ *
+ * @example define( 'NEWSPACK_DISABLE_AUTHORS_FILTER', true );
+ */
 if ( ! defined( 'NEWSPACK_DISABLE_AUTHORS_FILTER' ) || ! NEWSPACK_DISABLE_AUTHORS_FILTER ) {
 	Author_Filter::init();
 }

includes/bylines/class-bylines.php

@@ -53,6 +53,17 @@ public static function init() {
 	 * @return bool True if the feature is enabled, false otherwise.
 	 */
 	public static function is_enabled() {
+		/**
+		 * Disables Newspack's custom bylines feature which provides enhanced
+		 * author attribution capabilities beyond standard WordPress.
+		 *
+		 * @constant NEWSPACK_CUSTOM_BYLINES_DISABLED
+		 * @type     bool
+		 * @default  Custom bylines feature enabled
+		 * @status   draft
+		 *
+		 * @example define( 'NEWSPACK_CUSTOM_BYLINES_DISABLED', true );
+		 */
 		return ! defined( 'NEWSPACK_CUSTOM_BYLINES_DISABLED' ) || ! NEWSPACK_CUSTOM_BYLINES_DISABLED;
 	}
 

includes/class-admin-plugins-screen.php

@@ -214,6 +214,28 @@ public function enqueue_scripts_and_styles( $hook ) {
 		$installed_plugins   = array_values( array_intersect( array_keys( Plugin_Manager::get_managed_plugins() ), array_keys( Plugin_Manager::get_installed_plugins() ) ) );
 		$installed_plugins[] = 'newspack';
 
+		/**
+		 * URL to a plugin review request form. When set, displays a link
+		 * on the plugins screen for users to request plugin reviews.
+		 *
+		 * @constant NEWSPACK_PLUGIN_REVIEW_FORM_URL
+		 * @type     string
+		 * @default  No review form link shown
+		 * @status   draft
+		 *
+		 * @example define( 'NEWSPACK_PLUGIN_REVIEW_FORM_URL', 'https://example.com/plugin-review' );
+		 */
+		/**
+		 * URL to an approved plugins list. When set, displays a link
+		 * on the plugins screen to view pre-approved plugins.
+		 *
+		 * @constant NEWSPACK_APPROVED_PLUGINS_LIST_LINK
+		 * @type     string
+		 * @default  No approved plugins list link shown
+		 * @status   draft
+		 *
+		 * @example define( 'NEWSPACK_APPROVED_PLUGINS_LIST_LINK', 'https://example.com/approved-plugins' );
+		 */
 		$newspack_plugin_info = [
 			'plugins'                    => $plugins,
 			'installed_plugins'          => $installed_plugins,

includes/class-amp-enhancements.php

@@ -62,6 +62,18 @@ public static function should_use_amp_plus() {
 	 * @return bool Is AMP plus mode configured.
 	 */
 	public static function is_amp_plus_configured() {
+		/**
+		 * Enables AMP Plus mode which allows certain non-AMP-compatible scripts
+		 * to run on AMP pages. This includes Jetpack modules and Gravity Forms.
+		 * Use with caution as it may affect AMP validation.
+		 *
+		 * @constant NEWSPACK_AMP_PLUS_ENABLED
+		 * @type     bool
+		 * @default  AMP Plus mode disabled
+		 * @status   draft
+		 *
+		 * @example define( 'NEWSPACK_AMP_PLUS_ENABLED', true );
+		 */
 		return defined( 'NEWSPACK_AMP_PLUS_ENABLED' ) && NEWSPACK_AMP_PLUS_ENABLED;
 	}
 

includes/class-logger.php

@@ -21,6 +21,22 @@ class Logger {
 	 * @param string $type Type of the message.
 	 */
 	public static function log( $payload, $header = 'NEWSPACK', $type = 'info' ) {
+		/**
+		 * Controls logging verbosity across Newspack plugins.
+		 *
+		 * Levels:
+		 * - 0: Disabled (default)
+		 * - 1: Basic logging
+		 * - 2: Include caller function info
+		 * - 3+: Include data payload
+		 *
+		 * @constant NEWSPACK_LOG_LEVEL
+		 * @type     int
+		 * @default  Logging disabled (0)
+		 * @status   draft
+		 *
+		 * @example define( 'NEWSPACK_LOG_LEVEL', 2 );
+		 */
 		if ( ! defined( 'NEWSPACK_LOG_LEVEL' ) || 0 >= (int) NEWSPACK_LOG_LEVEL ) {
 			return;
 		}

includes/class-newspack.php

@@ -63,6 +63,17 @@ public static function load_textdomain() {
 	private function define_constants() {
 		define( 'NEWSPACK_VERSION', '0.0.1' );
 		define( 'NEWSPACK_ABSPATH', dirname( NEWSPACK_PLUGIN_FILE ) . '/' );
+		/**
+		 * Path to Composer's vendor directory. Override to use a shared vendor directory
+		 * across multiple plugins.
+		 *
+		 * @constant NEWSPACK_COMPOSER_ABSPATH
+		 * @type     string
+		 * @default  Plugin's vendor/ directory
+		 * @status   draft
+		 *
+		 * @example define( 'NEWSPACK_COMPOSER_ABSPATH', '/path/to/shared/vendor/' );
+		 */
 		if ( ! defined( 'NEWSPACK_COMPOSER_ABSPATH' ) ) {
 			define( 'NEWSPACK_COMPOSER_ABSPATH', dirname( NEWSPACK_PLUGIN_FILE ) . '/vendor/' );
 		}
@@ -331,6 +342,18 @@ public function deactivation_hook() {
 	 * @param WP_Screen $current_screen Current WP_Screen object.
 	 */
 	public static function restrict_user_access( $current_screen ) {
+		/**
+		 * Array of user IDs allowed to access plugin management screens
+		 * (plugins, plugin-install, plugin-editor). When defined, only listed
+		 * users can access these screens; others are redirected to the dashboard.
+		 *
+		 * @constant NEWSPACK_ALLOWED_PLUGIN_EDITORS
+		 * @type     array
+		 * @default  All users with appropriate capabilities can access plugin screens
+		 * @status   draft
+		 *
+		 * @example define( 'NEWSPACK_ALLOWED_PLUGIN_EDITORS', [ 1, 2, 3 ] );
+		 */
 		if ( ! defined( 'NEWSPACK_ALLOWED_PLUGIN_EDITORS' ) ) {
 			return;
 		}

includes/class-performance.php

@@ -91,6 +91,17 @@ public static function optimise_homepage_posts_block( $attributes ) {
 	 * Process the HTML output.
 	 */
 	public static function process_output_html() {
+		/**
+		 * Disables HTML output processing for performance optimizations.
+		 * Set to true to bypass any filters registered on 'newspack_output_html'.
+		 *
+		 * @constant NEWSPACK_DISABLE_HTML_PERF_PROCESSING
+		 * @type     bool
+		 * @default  HTML performance processing enabled
+		 * @status   draft
+		 *
+		 * @example define( 'NEWSPACK_DISABLE_HTML_PERF_PROCESSING', true );
+		 */
 		if ( defined( 'NEWSPACK_DISABLE_HTML_PERF_PROCESSING' ) && NEWSPACK_DISABLE_HTML_PERF_PROCESSING ) {
 			return;
 		}

includes/class-starter-content.php

@@ -226,6 +226,17 @@ public static function upload_logo() {
 	 * @return bool E2E testing environment?
 	 */
 	public static function is_e2e() {
+		/**
+		 * Indicates the site is running in E2E (end-to-end) testing mode.
+		 * Used to adjust behavior during automated testing.
+		 *
+		 * @constant NEWSPACK_IS_E2E
+		 * @type     bool
+		 * @default  Normal operation
+		 * @status   draft
+		 *
+		 * @example define( 'NEWSPACK_IS_E2E', true );
+		 */
 		return defined( 'NEWSPACK_IS_E2E' ) && NEWSPACK_IS_E2E;
 	}
 }

includes/content-gate/class-content-gate.php

@@ -92,6 +92,17 @@ public static function init() {
 	 * @return bool
 	 */
 	public static function is_newspack_feature_enabled() {
+		/**
+		 * Enables the content gating feature which allows restricting
+		 * content access based on membership, donations, or other criteria.
+		 *
+		 * @constant NEWSPACK_CONTENT_GATES
+		 * @type     bool
+		 * @default  Content gates disabled
+		 * @status   draft
+		 *
+		 * @example define( 'NEWSPACK_CONTENT_GATES', true );
+		 */
 		return defined( 'NEWSPACK_CONTENT_GATES' ) && NEWSPACK_CONTENT_GATES;
 	}
 

includes/oauth/class-google-oauth.php

@@ -469,6 +469,17 @@ public static function remove_credentials() {
 	 * Is Google OAuth configured?
 	 */
 	public static function is_oauth_configured() {
+		/**
+		 * Disables Google OAuth integration even if the OAuth proxy is configured.
+		 * Use this to prevent Google sign-in on specific environments.
+		 *
+		 * @constant NEWSPACK_DISABLE_GOOGLE_OAUTH
+		 * @type     bool
+		 * @default  Google OAuth enabled (if proxy configured)
+		 * @status   draft
+		 *
+		 * @example define( 'NEWSPACK_DISABLE_GOOGLE_OAUTH', true );
+		 */
 		return OAuth::is_proxy_configured( 'google' ) && ( ! defined( 'NEWSPACK_DISABLE_GOOGLE_OAUTH' ) || ! NEWSPACK_DISABLE_GOOGLE_OAUTH );
 	}
 }