use phpDocumentor 3 + misc doc comment cleanup (#68)

Author: eli-darkly

.gitignore

@@ -7,4 +7,5 @@ composer.phar
 integration-tests/vendor
 composer.lock
 docs/build
+docs/.phpdoc
 .phpunit.result.cache

.ldrelease/build-docs.sh

@@ -1,6 +1,9 @@
 #!/bin/bash
 
+# This script assumes that it is running in a Docker container using the image
+# "ldcircleci/php-sdk-release", defined in https://github.com/launchdarkly/sdks-ci-docker
+
 set -e
 
 cd docs
-make PHPDOC_ARCHIVE=/home/circleci/ldtools/phpDocumentor.phar  # provided in ldcircleci/ld-php-sdk-release image
+make

.ldrelease/config.yml

@@ -8,7 +8,7 @@ publications:
 
 circleci:
   linux:
-    image: ldcircleci/ld-php-sdk-release:1  # built in sdks-ci-docker project, contains PHP 7.2 + phpDocumentor
+    image: ldcircleci/php-sdk-release:1  # built in sdks-ci-docker project, contains PHP 7.3 + phpDocumentor 3
 
 documentation:
   githubPages: true

docs/Makefile

@@ -1,17 +1,18 @@
 
-# PHPDOC_ARCHIVE is overridden in the CircleCI release
-PHPDOC_ARCHIVE := $(shell pwd)/build/phpDocumentor.phar
-OUTPUT_DIR := $(shell pwd)/build
-PHPDOC_URL=https://www.phpdoc.org/phpDocumentor.phar
+SOURCE_DIR = $(shell cd .. && pwd)
+PHPDOCUMENTOR = php $(LDTOOLS_DIR)/php/phpDocumentor.phar
 
-.PHONY: install html
+.PHONY: html
 
-html: install
+html:
 	rm -rf build/temp build/html
-	cd .. && php $(PHPDOC_ARCHIVE) --visibility public --title "LaunchDarkly PHP SDK ${LD_RELEASE_VERSION}"
-
-install: $(PHPDOC_ARCHIVE)
-
-$(PHPDOC_ARCHIVE):
-	mkdir -p build
-	cd build && unzip ../lib/phpDocumentor.phar.zip
+	$(PHPDOCUMENTOR) \
+		-d $(SOURCE_DIR) \
+		-t build/html \
+		--ignore vendor/ \
+		--ignore tests/ \
+		--ignore docs/ \
+		--ignore src/LaunchDarkly/Impl \
+		--visibility public \
+		--defaultpackagename "SDK" \
+		--title "LaunchDarkly PHP SDK ${LD_RELEASE_VERSION}"

src/LaunchDarkly/EvaluationDetail.php

@@ -7,7 +7,7 @@
 /**
  * An object that combines the result of a flag evaluation with an explanation of how it was calculated.
  *
- * This is returned by {@link \LaunchDarkly\LDClient::variationDetail()}.
+ * This is returned by {@see \LaunchDarkly\LDClient::variationDetail()}.
  */
 class EvaluationDetail
 {

src/LaunchDarkly/EvaluationReason.php

@@ -5,7 +5,7 @@
 /**
  * Describes the reason that a flag evaluation produced a particular value.
  *
- * This is part of the {@link \LaunchDarkly\EvaluationDetail} object returned by {@link \LaunchDarkly\LDClient::variationDetail()}.
+ * This is part of the {@see \LaunchDarkly\EvaluationDetail} object returned by {@see \LaunchDarkly\LDClient::variationDetail()}.
  */
 class EvaluationReason implements \JsonSerializable
 {

src/LaunchDarkly/EventPublisher.php

@@ -4,12 +4,15 @@
 /**
  * Interface for the component that sends events to the LaunchDarkly service.
  *
- * The default implementation is {@link \LaunchDarkly\Integrations\Curl::eventPublisher()}. The SDK also
- * provides {@link \LaunchDarkly\Integrations\Guzzle::eventPublisher()}.
+ * The default implementation is {@see \LaunchDarkly\Integrations\Curl::eventPublisher()}. The SDK also
+ * provides {@see \LaunchDarkly\Integrations\Guzzle::eventPublisher()}.
  */
 interface EventPublisher
 {
-    /** @var int */
+    /**
+     * @var int
+     * @ignore
+     */
     const CURRENT_SCHEMA_VERSION = 2;
 
     /**

src/LaunchDarkly/FeatureFlagsState.php

@@ -2,11 +2,12 @@
 namespace LaunchDarkly;
 
 use LaunchDarkly\Impl\Model\FeatureFlag;
+use LaunchDarkly\LDClient;
 
 /**
  * A snapshot of the state of all feature flags with regard to a specific user.
  *
- * This is generated by calling {@link \LaunchDarkly\LDClient::allFlagsState()}.
+ * This is generated by calling {@see \LaunchDarkly\LDClient::allFlagsState()}.
  *
  * Serializing this object to JSON using json_encode(), or the jsonSerialize() method, will produce the
  * appropriate data structure for bootstrapping the LaunchDarkly JavaScript client. See the SDK
@@ -87,11 +88,12 @@ public function getFlagValue(string $key)
     }
 
     /**
-     * Returns the evaluation reason for an individual feature flag (as returned by LDClient.variationDetail())
+     * Returns the evaluation reason for an individual feature flag (as returned by variationDetail())
      * at the time the state was recorded.
      * @param string $key the feature flag key
      * @return EvaluationReason|null the evaluation reason; null if reasons were not recorded, or if there
      * was no such flag
+     * @see \LaunchDarkly\LDClient::variationDetail()
      */
     public function getFlagReason(string $key): ?EvaluationReason
     {
@@ -103,9 +105,10 @@ public function getFlagReason(string $key): ?EvaluationReason
     }
 
     /**
-     * Returns an associative array of flag keys to flag values. If a flag would have evaluated to the default
-     * value, its value will be null.
-     * <p>
+     * Returns an associative array of flag keys to flag values.
+     * 
+     * If a flag would have evaluated to the default value, its value will be null.
+     * 
      * Do not use this method if you are passing data to the front end to "bootstrap" the JavaScript client.
      * Instead, use jsonSerialize().
      * @return array an associative array of flag keys to JSON values
@@ -117,9 +120,10 @@ public function toValuesMap(): array
 
     /**
      * Returns a JSON representation of the entire state map (as an associative array), in the format used
-     * by the LaunchDarkly JavaScript SDK. Use this method if you are passing data to the front end in
-     * order to "bootstrap" the JavaScript client.
-     * <p>
+     * by the LaunchDarkly JavaScript SDK.
+     * 
+     * Use this method if you are passing data to the front end in order to "bootstrap" the JavaScript client.
+     * 
      * Note that calling json_encode() on a FeatureFlagsState object will automatically use the
      * jsonSerialize() method.
      * @return array an associative array suitable for passing as a JSON object

src/LaunchDarkly/FeatureRequester.php

@@ -7,7 +7,7 @@
 /**
  * Interface for the component that retrieves feature flag data.
  *
- * The default implementation is {@link \LaunchDarkly\Integrations\Guzzle::featureRequester()}, which requests
+ * The default implementation is {@see \LaunchDarkly\Integrations\Guzzle::featureRequester()}, which requests
  * flags inefficiently via HTTP on demand. For other implementations, including database integrations, see the
  * LaunchDarkly\Integrations namespace.
  */

src/LaunchDarkly/Impl/Integrations/FeatureRequesterBase.php

@@ -42,8 +42,8 @@ protected function __construct(string $baseUri, string $sdkKey, array $options)
     /**
      * Override this method to read a JSON object (as a string) from the underlying store.
      *
-     * @param $namespace "features" or "segments"
-     * @param $key flag or segment key
+     * @param string $namespace "features" or "segments"
+     * @param string $key flag or segment key
      * @return string|null the stored JSON data, or null if not found
      */
     protected function readItemString(string $namespace, string $key): ?string
@@ -54,7 +54,7 @@ protected function readItemString(string $namespace, string $key): ?string
     /**
      * Override this method to read a set of JSON objects (as strings) from the underlying store.
      *
-     * @param $namespace "features" or "segments"
+     * @param string $namespace "features" or "segments"
      * @return array|null array of stored JSON strings
      */
     protected function readItemStringList(string $namespace): ?array
@@ -76,7 +76,7 @@ protected function createCache(array $options): ?FeatureRequesterCache
     /**
      * Gets an individual feature flag.
      *
-     * @param $key string feature flag key
+     * @param string $key feature flag key
      * @return FeatureFlag|null The decoded JSON feature data, or null if missing
      */
     public function getFeature(string $key): ?FeatureFlag
@@ -98,7 +98,7 @@ public function getFeature(string $key): ?FeatureFlag
     /**
      * Gets an individual user segment.
      *
-     * @param $key string segment key
+     * @param string $key segment key
      * @return Segment|null The decoded JSON segment data, or null if missing
      */
     public function getSegment(string $key): ?Segment

src/LaunchDarkly/Impl/Integrations/FeatureRequesterCache.php

@@ -6,16 +6,16 @@ interface FeatureRequesterCache
     /**
      * Read a value from the cache.
      *
-     * @param $cacheKey the unique key
+     * @param string $cacheKey the unique key
      * @return string the cached value, or null if not found
      */
     public function getCachedString(string $cacheKey): ?string;
 
     /**
      * Store a value in the cache.
      *
-     * @param $cacheKey the unique key
-     * @param $data the string value
+     * @param string $cacheKey the unique key
+     * @param string $data the string value
      */
     public function putCachedString(string $cacheKey, ?string $data): void;
 }

src/LaunchDarkly/Impl/Integrations/GuzzleFeatureRequester.php

@@ -60,7 +60,7 @@ public function __construct(string $baseUri, string $sdkKey, array $options)
     /**
      * Gets feature data from a likely cached store
      *
-     * @param $key string feature key
+     * @param string $key feature key
      * @return FeatureFlag|null The decoded FeatureFlag, or null if missing
      */
     public function getFeature(string $key): ?FeatureFlag
@@ -83,7 +83,7 @@ public function getFeature(string $key): ?FeatureFlag
     /**
      * Gets segment data from a likely cached store
      *
-     * @param $key string segment key
+     * @param string $key segment key
      * @return Segment|null The decoded Segment, or null if missing
      */
     public function getSegment(string $key): ?Segment

src/LaunchDarkly/Impl/PreloadedFeatureRequester.php

@@ -28,7 +28,7 @@ public function __construct(FeatureRequester $baseRequester, array $knownFeature
     /**
      * Gets feature data from cached values
      *
-     * @param $key feature key
+     * @param string $key feature key
      * @return FeatureFlag|null The decoded FeatureFlag, or null if missing
      */
     public function getFeature(string $key): ?FeatureFlag
@@ -42,7 +42,7 @@ public function getFeature(string $key): ?FeatureFlag
     /**
      * Gets segment data from the regular feature requester
      *
-     * @param $key segment key
+     * @param string $key segment key
      * @return Segment|null The decoded Segment, or null if missing
      */
     public function getSegment(string $key): ?Segment

src/LaunchDarkly/Impl/SemanticVersion.php

@@ -45,8 +45,8 @@ public function __construct(
 
     /**
      * Attempts to parse a string as a semantic version.
-     * @param $input string the input string
-     * @param $loose boolean true if minor and patch versions can be omitted
+     * @param string $input the input string
+     * @param bool $loose true if minor and patch versions can be omitted
      * @throws \InvalidArgumentException if the string is not in an acceptable format
      */
     public static function parse(string $input, bool $loose = false): SemanticVersion
@@ -67,7 +67,7 @@ public static function parse(string $input, bool $loose = false): SemanticVersio
 
     /**
      * Compares this version to another version using Semantic Versioning precedence rules.
-     * @param $other a SemanticVersion object
+     * @param SemanticVersion $other a SemanticVersion object
      * @return int -1 if this version has lower precedence than the other version; 1 if this version
      *   has higher precedence; zero if the two have equal precedence
      */

src/LaunchDarkly/Integrations/Curl.php

@@ -21,7 +21,7 @@ class Curl
      *     $client = new LDClient("sdk_key", $config);
      *
      * This implementation forks a process for each event payload. Alternatively, you can use
-     * {@link \LaunchDarkly\Integrations\Guzzle::eventPublisher()}, which makes synchronous requests.
+     * {@see \LaunchDarkly\Integrations\Guzzle::eventPublisher()}, which makes synchronous requests.
      *
      * @param array $options  Configuration settings (can also be passed in the main client configuration):
      *   - `curl`: command for executing `curl`; defaults to `/usr/bin/env curl`

src/LaunchDarkly/Integrations/Guzzle.php

@@ -33,7 +33,7 @@ public static function featureRequester($options = array())
     /**
      * Configures an adapter for sending analytics events to LaunchDarkly using GuzzleHttp.
      *
-     * The default mechanism for sending events is {@link \LaunchDarkly\Integrations\Curl::eventPublisher()}.
+     * The default mechanism for sending events is {@see \LaunchDarkly\Integrations\Curl::eventPublisher()}.
      * To use Guzzle instead, call this method and store its return value in the `event_publisher` property
      * of the client configuration:
      *

src/LaunchDarkly/LDClient.php

@@ -55,29 +55,30 @@ class LDClient
      *
      * @param string $sdkKey The SDK key for your account
      * @param array $options Client configuration settings
-     *     - `base_uri`: Base URI of the LaunchDarkly service. Change this if you are connecting to a Relay Proxy instance instead of
+     * - `base_uri`: Base URI of the LaunchDarkly service. Change this if you are connecting to a Relay Proxy instance instead of
      * directly to LaunchDarkly.
-     *     - `events_uri`: Base URI for sending events to LaunchDarkly. Change this if you are forwarding events through a Relay Proxy instance.
-     *     - `timeout`: The maximum length of an HTTP request in seconds. Defaults to 3.
-     *     - `connect_timeout`: The maximum number of seconds to wait while trying to connect to a server. Defaults to 3.
-     *     - `cache`: An optional implementation of Guzzle's [CacheStorageInterface](https://github.com/Kevinrob/guzzle-cache-middleware/blob/master/src/Storage/CacheStorageInterface.php).
+     * - `events_uri`: Base URI for sending events to LaunchDarkly. Change this if you are forwarding events through a Relay Proxy instance.
+     * - `timeout`: The maximum length of an HTTP request in seconds. Defaults to 3.
+     * - `connect_timeout`: The maximum number of seconds to wait while trying to connect to a server. Defaults to 3.
+     * - `cache`: An optional implementation of Guzzle's [CacheStorageInterface](https://github.com/Kevinrob/guzzle-cache-middleware/blob/master/src/Storage/CacheStorageInterface.php).
      * Defaults to an in-memory cache.
-     *     - `send_events`: If set to false, disables the sending of events to LaunchDarkly. Defaults to true.
-     *     - `logger`: An optional implementation of [Psr\Log\LoggerInterface](https://www.php-fig.org/psr/psr-3/). Defaults to a
+     * - `send_events`: If set to false, disables the sending of events to LaunchDarkly. Defaults to true.
+     * - `logger`: An optional implementation of [Psr\Log\LoggerInterface](https://www.php-fig.org/psr/psr-3/). Defaults to a
      * Monolog\Logger sending all messages to the PHP error_log.
-     *     - `offline`: If set to true, disables all network calls and always returns the default value for flags. Defaults to false.
-     *     - `feature_requester`: An optional {@link \LaunchDarkly\FeatureRequester} implementation, or a class or factory for one.
-     * Defaults to {@link \LaunchDarkly\Integrations\Guzzle::featureRequester()}.
-     *     - `feature_requester_class`: Deprecated, equivalent to feature_requester.
-     *     - `event_publisher`: An optional {@link \LaunchDarkly\EventPublisher} implementation, or a class or factory for one.
-     * Defaults to {@link \LaunchDarkly\Integrations\Curl::eventPublisher()}.
-     *     - `event_publisher_class`: Deprecated, equivalent to event_publisher.
-     *     - `all_attributes_private`: If set to true, no user attributes (other than the key) will be sent back to LaunchDarkly.
+     * - `offline`: If set to true, disables all network calls and always returns the default value for flags. Defaults to false.
+     * - `feature_requester`: An optional {@see \LaunchDarkly\FeatureRequester} implementation, or a class or factory for one.
+     * Defaults to {@see \LaunchDarkly\Integrations\Guzzle::featureRequester()}. There are also optional packages providing
+     * database integrations; see [Storing data](https://docs.launchdarkly.com/sdk/features/storing-data#php).
+     * - `feature_requester_class`: Deprecated, equivalent to feature_requester.
+     * - `event_publisher`: An optional {@see \LaunchDarkly\EventPublisher} implementation, or a class or factory for one.
+     * Defaults to {@see \LaunchDarkly\Integrations\Curl::eventPublisher()}.
+     * - `event_publisher_class`: Deprecated, equivalent to event_publisher.
+     * - `all_attributes_private`: If set to true, no user attributes (other than the key) will be sent back to LaunchDarkly.
      * Defaults to false.
-     *     - `private_attribute_names`: An optional array of user attribute names to be marked private. Any users sent to LaunchDarkly
+     * - `private_attribute_names`: An optional array of user attribute names to be marked private. Any users sent to LaunchDarkly
      * with this configuration active will have attributes with these names removed. You can also set private attributes on a
      * per-user basis in LDUserBuilder.
-     *     - Other options may be available depending on any features you are using from the LaunchDarkly\Integrations namespace.
+     * - Other options may be available depending on any features you are using from the `LaunchDarkly\Integrations` namespace.
      *
      * @return LDClient
      */
@@ -327,16 +328,16 @@ public function identify(LDUser $user): void
      * Returns an object that encapsulates the state of all feature flags for a given user.
      *
      * This includes the flag values as well as other flag metadata that may be needed by front-end code,
-     * since the most common use case for this method is [bootstrapping](https://docs.launchdarkly.com/docs/js-sdk-reference#section-bootstrapping)
+     * since the most common use case for this method is [bootstrapping](https://docs.launchdarkly.com/sdk/features/bootstrapping)
      * in conjunction with the JavaScript browser SDK.
      *
      * This method does not send analytics events back to LaunchDarkly.
      *
      * @param LDUser $user The end user requesting the feature flags
      * @param array $options Optional properties affecting how the state is computed:
-     *     - `clientSideOnly`: Set this to true to specify that only flags marked for client-side use
+     * - `clientSideOnly`: Set this to true to specify that only flags marked for client-side use
      * should be included; by default, all flags are included
-     *     - `withReasons`: Set this to true to include evaluation reasons (see {@link variationDetail()})
+     * - `withReasons`: Set this to true to include evaluation reasons (see {@see \LaunchDarkly\LDClient::variationDetail()})
      * @return FeatureFlagsState a FeatureFlagsState object (will never be null)
      */
     public function allFlagsState(LDUser $user, array $options = array()): FeatureFlagsState
@@ -406,7 +407,7 @@ public function alias(LDUser $user, LDUser $previousUser): void
     /**
      * Generates an HMAC sha256 hash for use in Secure mode.
      *
-     * See: https://docs.launchdarkly.com/docs/js-sdk-reference#section-secure-mode
+     * See: [Secure mode](https://docs.launchdarkly.com/sdk/features/secure-mode)
      */
     public function secureModeHash(LDUser $user): string
     {

src/LaunchDarkly/LDUser.php

@@ -7,7 +7,7 @@
  * The only mandatory property property is the key, which must uniquely identify each user. For authenticated users,
  * this may be a username or e-mail address. For anonymous users, it could be an IP address or session ID.
  *
- * Use {@link \LaunchDarkly\LDUserBuilder} to construct instances of this class.
+ * Use {@see \LaunchDarkly\LDUserBuilder} to construct instances of this class.
  */
 class LDUser
 {
@@ -48,7 +48,9 @@ class LDUser
     protected $_privateAttributeNames = array();
 
     /**
-     * Constructor for directly creating an instance; it is preferable to use LDUserBuilder.
+     * Constructor for directly creating an instance.
+     * 
+     * It is preferable to use {@see LDUserBuilder} instead of this constructor.
      *
      * @param string $key Unique key for the user. For authenticated users, this may be a username or e-mail address. For anonymous users, this could be an IP address or session ID.
      * @param string|null $secondary An optional secondary identifier